docs.docker.com Paid content

OpenAPI-generated API documentation is reference documentation that is produced automatically from an OpenAPI description file rather than written by hand. You write (or generate) a machine-readable specification of your API — endpoints, parameters, request bodies, responses, schemas, and auth — and a documentation tool reads that file and renders a browsable, often interactive reference site. The spec becomes the single source of truth; the docs become a build artifact.

This differs from manually written docs in one fundamental way: with hand-written docs, the prose is the source of truth and the API is described separately. With spec-driven docs, the API description is the source, and every page, table, and code sample is derived from it.

How the workflow actually runs

A typical spec-driven documentation pipeline has five stages:

1. Author or generate the spec. You either write an OpenAPI document by hand (YAML or JSON), or generate it from code annotations, framework metadata, or a design-first editor. Design-first means the spec is written before implementation; code-first means it is extracted from existing code.
2. Validate and lint. The spec is checked against the OpenAPI schema and against style rules — consistent naming, required descriptions, no undocumented 4xx responses, no orphaned schemas.
3. Bundle and transform. Multi-file specs are combined, $ref pointers are resolved, and the document is optionally split into per-tag or per-version outputs.
4. Render. A documentation tool converts the spec into HTML: an endpoint list, a sidebar of operations, parameter tables, response schemas, and a "try it" console.
5. Publish and version. The rendered site is deployed, and each API version gets its own snapshot so consumers can read docs matching the version they call.

Steps 2 through 5 are usually automated in CI. If the spec fails validation, the docs build fails — which is the point.

Spec-driven vs. hand-written documentation

The practical conclusion most teams reach: generate the reference, write the guides. Reference material is repetitive and mechanical, which is exactly what generation is good at. Conceptual explanations, migration notes, and tutorials carry judgment that a spec cannot express.

What you get out of the box

Generated reference pages commonly include:

• An operation list grouped by tag or path, with HTTP method and path.
• Parameter tables showing name, location (path, query, header, cookie), type, required flag, and description.
• Request and response schemas rendered as expandable trees, including nested objects and arrays.
• Authentication details pulled from the securitySchemes section.
• Interactive request consoles that let a reader send a real call from the browser.
• Generated code samples in several languages, derived from the same schemas.
• Multiple output formats, such as a static site, a single HTML file, or a mock server.

Because all of these come from one document, changing a field name in the spec updates the parameter table, the schema tree, and every code sample at once.

Where spec-driven documentation breaks down

Generation is not free. The trade-offs are real:

Spec quality becomes documentation quality. A field with no description produces a table row with an empty cell. A vague summary produces a vague heading. Tools can enforce presence of descriptions via linting, but they cannot enforce that the description is useful.

Customization has limits. If you need a page that does not map to an OpenAPI concept — a conceptual overview, a pricing explanation, a comparison of two endpoints — you write it outside the generator and link to it.

Not everything is expressible. Webhooks, streaming responses, long-polling behavior, and complex multi-step flows are awkward or impossible to describe fully in OpenAPI. Those need prose.

The spec can go stale. If the spec is maintained separately from the implementation, it drifts just like hand-written docs. The mitigation is to generate the spec from code, or to test the implementation against the spec in CI.

Interactive consoles need care. A "try it" button that hits a production API with real credentials is a security and rate-limit problem. Point it at a sandbox, or disable it.

Deciding whether to adopt it

Adopt spec-driven reference documentation if most of these are true:

• Your API has more than a handful of endpoints, or changes frequently.
• You ship client SDKs or code samples in more than one language.
• Multiple teams consume the API and need a consistent, always-current reference.
• You already have, or are willing to maintain, an OpenAPI description.

Stay with hand-written docs, or a hybrid, if:

• Your API is small and stable, and the reference fits on one page.
• Your documentation is mostly conceptual and contains little endpoint-level detail.
• You cannot commit to keeping the spec in sync with the implementation.

A reasonable middle path: generate the reference from the spec, and hand-write the getting-started guide, authentication walkthrough, and error-handling page. Link the two directions so readers can move from concept to endpoint and back.

A minimal starting checklist

1. Produce one valid OpenAPI document for a single API version.
2. Add a linter with rules for descriptions, operation IDs, and error responses.
3. Wire the docs build into CI so a failing spec fails the build.
4. Render the reference and review it as a reader, not as the author.
5. Write the two or three conceptual pages the generator cannot produce.
6. Version the published docs alongside the API version.

The core idea is simple: describe the API once, in a format both machines and humans can read, and let the reference documentation fall out of that description. Everything else — tooling, hosting, interactivity — is a detail on top of that decision.

Docker's official documentation lives at docs.docker.com, and it is organized so that a beginner can move from "I've never installed Docker" to "my app runs in a container" without leaving the site. The fastest path is: install Docker, complete the Get Started tutorial, then jump to a language-specific guide for your stack. Use the Reference section only when you need exact command syntax, and browse Samples when you want a working project to copy.

This guide explains what each section of Docker Docs is for, gives you a reading order, and shows you how to find things quickly once you're past the basics.

What the main sections of Docker Docs are for

Docker Docs is not a single manual — it's a set of distinct areas, each written for a different moment in your learning. Knowing which one to open saves a lot of time.

The key distinction: Guides and Get Started teach you by doing; Reference tells you exactly what a command accepts. Beginners often get stuck in Reference too early, reading option lists without context. Start with the doing, then look up the details.

A step-by-step reading path for your first container

Follow this order the first time. Each step has a clear "you're done when…" signal.

Step 1: Install Docker

Open the Get Started area and find the installation instructions for your operating system (Docker Desktop for Windows and macOS, or the engine packages for Linux). Install it and confirm it works by running the version check command shown in the docs.

You're done when: a docker command in your terminal returns version information instead of "command not found."

Step 2: Complete the Get Started tutorial

The Get Started tutorial is the single most valuable page for a beginner. It walks you through building an image, running it as a container, and stopping it — using a small sample app so nothing is left to guesswork. Do every command yourself rather than reading passively.

You're done when: you have built an image and seen your container produce output.

Step 3: Understand the core concepts

Before containerizing your own project, read the conceptual material on images, containers, and registries. This is where the mental model clicks: an image is the packaged blueprint, a container is a running instance of it, and a registry is where images are stored and shared.

You're done when: you can explain in one sentence why you build an image before you run a container.

Step 4: Write your first Dockerfile

A Dockerfile is the text file that describes how to build your image. Find the Dockerfile reference in the docs and read the instructions you'll actually use first: FROM, WORKDIR, COPY, RUN, EXPOSE, and CMD. Don't try to learn every instruction — most projects use a small handful.

You're done when: you have a Dockerfile in your project that builds without errors.

Step 5: Build and run your own app

Return to the Guides section and find the guide closest to your language or framework. These guides follow the same build-and-run pattern as the tutorial but applied to real application types, so you can adapt the steps to your code.

You're done when: your own application responds correctly from inside a container.

How to find things fast once you're moving

After the first container works, your needs shift from "learn the flow" to "look up one specific thing." Use these entry points:

• Search — the search box at the top of Docker Docs is the quickest route to a command or instruction. Type the exact command name (for example, a docker run flag) rather than a vague phrase.
• CLI reference — every docker subcommand, its flags, and examples. This is your lookup table, not a tutorial.
• Dockerfile reference — every instruction with syntax and notes. Check here before guessing at an option.
• Compose file reference — when your app grows to multiple containers, this defines them in one file.
• API reference — for when you automate Docker from code instead of the terminal.
• Samples — full projects organized by language and use case. Cloning a sample and modifying it is often faster than starting from a blank file.

A practical habit: when a command fails, copy the exact error into search. The docs pages for commands and instructions usually include the conditions that produce common errors.

Guides vs. Reference: which one do you need right now?

This is the distinction that trips up most beginners, so make it explicit:

• Use a Guide when you are trying to accomplish a task and don't yet know the steps. Guides assume you want an outcome and lead you there.
• Use Reference when you already know the task and need the exact spelling, flag, or field. Reference assumes you know what you're doing and just need precision.

If you find yourself reading a long list of options and feeling lost, you're in Reference too early — go back to a Guide. If you're following a tutorial and it doesn't cover the specific option you need, that's your cue to switch to Reference for that one detail, then return.

A reusable checklist for containerizing any app

Keep this sequence handy for each new project:

1. Confirm Docker is installed and running.
2. Identify your app's language and framework, then open the matching Guide.
3. Write a minimal Dockerfile using only the instructions you need.
4. Build the image and fix any errors using the Dockerfile reference.
5. Run the container and verify the app responds.
6. Add a .dockerignore file so unnecessary files aren't copied into the image.
7. When you add a second service (a database, for example), move to the Compose file reference.
8. Save the commands that worked so you can repeat them next time.

Where to go after your first container

Once one app runs in a container, the natural next steps are multi-container setups with Compose, sharing images through a registry, and automating builds. Each of these has its own Guide and Reference area on Docker Docs, so the same pattern applies: read the Guide to learn the flow, then keep the Reference open for exact syntax.

The documentation is large, but you never need all of it at once. Install, do the Get Started tutorial, containerize your own app with a language guide, and look things up in Reference only when you need a precise answer. That path takes you from zero to a working container without detours.

When a Docker build fails or a container exits immediately, the fix usually starts with reading the error correctly. Docker separates two phases: build time (the image is being created from your Dockerfile) and run time (a container is starting from a finished image). Most errors belong clearly to one phase, and identifying the phase narrows the cause quickly. This guide walks through how to read the output, isolate the layer where things break, and use Docker CLI commands to inspect and debug.

First: Decide Which Phase Is Failing

If you are unsure, run the build and the container separately rather than chaining them. That alone tells you which half of the problem you own.

Reading Docker Build Output

Build output is sequential. The failure is almost always at the last step shown, not the first. Docker prints each instruction and its result; the first non-zero exit stops the build.

Common build errors and their root causes

COPY failed: file not found in build context The path you referenced does not exist relative to the build context you passed. Check that:

• The file is inside the directory given to docker build (often .).
• A .dockerignore file is not excluding it.
• You are not copying from outside the context (Docker cannot reach parent directories).

RUN command returns exit code 1 (or another non-zero) The command inside the container failed. This is usually an application-level problem, not a Docker problem: a missing package, a wrong path, a failed download, or a command that assumes a shell feature your base image lacks. Read the lines above the error — the real message is often printed there.

failed to solve / buildkit errors BuildKit reports the failing instruction and often a hint. Treat the hint as a starting point, not a guarantee. Reproduce the failing command manually by running an interactive container from the previous stage's image.

no matching manifest for <platform> The image you are pulling does not publish a variant for your architecture. Confirm the image supports your platform, or build for the platform the image provides.

A practical build-debug loop

1. Build with plain output so steps are visible: docker build -t myapp .
2. Note the last successful step.
3. Start an interactive shell from that intermediate image (or from the base image) and run the failing command by hand.
4. Fix the Dockerfile, rebuild, repeat.

If the build is slow, reorder instructions so frequently changing steps come last — but do this only after the error is fixed, not while debugging.

Reading Container Startup Failures

A container that exits immediately is doing what it was told: its main process ended. Docker does not keep a container alive if its entrypoint/command finishes.

Step 1: Get the exit code

docker ps -a

Look at the STATUS column. An exit code of 0 usually means the process completed successfully but was not meant to be a long-running service. Codes like 1, 127, or 137 point to different causes:

• 127 — command not found (wrong entrypoint, missing binary, or a shell path issue).
• 1 — general application error; check logs.
• 137 — the process was killed, often out of memory or a manual stop.

Step 2: Read the logs

docker logs <container_id>

If the logs are empty, the process may have failed before producing output — a strong sign of a bad entrypoint or a missing executable. Confirm what the container is actually trying to run:

docker inspect <container_id>

Check the Config.Cmd and Config.Entrypoint fields. A common mistake is an entrypoint that references a file not present in the final image, or a shell form that swallows arguments.

Step 3: Run it interactively

Override the entrypoint to get a shell and explore the container's filesystem:

docker run -it --entrypoint sh <image>

From inside, verify the binary exists, the working directory is what you expect, and environment variables are set. This is the fastest way to separate "the image is wrong" from "the runtime configuration is wrong."

Step 4: Check runtime configuration

If the image works interactively but fails normally, the problem is likely configuration:

• Missing environment variables — the app exits when a required variable is absent.
• Port conflicts — the container starts but the host port is already in use; the error appears in docker run output.
• Volume mounts — a mount can hide files the image expected, or point at an empty host directory.
• Networking — the container cannot reach a dependency it needs at startup.

Isolating Dockerfile vs. Image vs. Runtime

Use this decision path:

1. Does the build succeed? If no, the problem is in the Dockerfile or build context.
2. Does the image run interactively? If yes but the normal run fails, the problem is runtime configuration (env, ports, volumes, command).
3. Does it fail in both? The image itself is incomplete — a missing dependency or file baked in at build time.
4. Does it work locally but fail elsewhere? Compare environment, architecture, and mounted data between the two environments.

When to Consult Docker Docs

The official documentation at docs.docker.com is the right reference for:

• CLI command flags — exact options for docker build, docker run, docker inspect, and docker logs.
• Dockerfile instruction semantics — how COPY, RUN, ENTRYPOINT, and CMD interact, especially the difference between shell and exec form.
• Build context and .dockerignore — what gets sent to the daemon and what is excluded.
• Registry and authentication — pull failures tied to login or access.

Use the docs to confirm behavior, not to guess at it. Error messages are usually literal; the documentation explains the rules behind them.

A Reusable Debugging Checklist

• [ ] Identify the failing phase: build or run.
• [ ] For builds, read the last STEP and the lines above the error.
• [ ] For runs, get the exit code with docker ps -a.
• [ ] Read docker logs before changing anything.
• [ ] Inspect Entrypoint and Cmd with docker inspect.
• [ ] Reproduce interactively with --entrypoint sh.
• [ ] Check env vars, ports, and volume mounts.
• [ ] Confirm the image supports your platform.
• [ ] Only then edit the Dockerfile or run command.

Most Docker errors are not mysterious once you know which phase failed and where to look. Read the last step, check the exit code, read the logs, and reproduce interactively. That sequence resolves the large majority of build and startup failures without guesswork.