docker-library/docker: Packaging the Docker Official Image

Why docker-library/docker exists

docker-library/docker solves a packaging problem rather than a basic Docker installation problem. It is the Git repository for the Docker Official Image named `docker`, published through the Docker Hub `_/docker` page. The intended contributors are people who need to define, update, or review the contents of that image. Ordinary engineers looking for a ready-to-run Docker image should begin with Docker Hub, while engineers looking to reproduce or change the image should inspect this repository.

The repository separates image definitions by deployment model. The visible layout includes `Dockerfile-cli.template` for a CLI-oriented image, `Dockerfile-dind.template` for Docker-in-Docker, `Dockerfile-dind-rootless.template` for a rootless dind variant, and `Dockerfile-windows-servercore.template` for a Windows Server Core variant. This separation matters because these variants serve different runtime requirements. The image also includes the `29/` directory, but the README does not explain what that directory contains.

The repository does not describe itself as a distribution channel for the Docker Engine binaries themselves. Its scope is the packaging metadata and supporting scripts used to construct the Official Image. That boundary is important when evaluating the project: changes here are image-maintenance work, while instructions for using Docker as software belong on the Docker Hub page.

Template and script structure behind the image

Based on the repository layout, the image definitions are driven by several Dockerfile templates rather than one obvious Dockerfile. The naming convention separates CLI, standard dind, rootless dind, and Windows Server Core cases. Shell support files include `apply-templates.sh`, `update.sh`, `versions.sh`, `docker-entrypoint.sh`, `dockerd-entrypoint.sh`, and `modprobe.sh`. The exact contents of those files are not reproduced here, so their individual behavior cannot be confirmed.

Version selection appears to involve `versions.json` and `versions.sh`. A separate `shared.jq` file indicates that JSON processing is part of the repository tooling, while `generate-stackbrew-library.sh` performs a separate generation function by name. The repository therefore appears to contain both image-definition templates and supporting automation, but the README does not document the order in which those scripts run or the inputs they consume.

This structure creates a clear division between configuration and generated or applied artifacts. Templates describe image variants, while shell and `jq`-related files support version handling and generation. However, the README does not provide a dependency list, build command, template substitution contract, or architecture matrix. Contributors cannot confirm the complete pipeline from the README alone and would need to inspect those repository files.

Finding the authoritative Docker usage documentation

A first-time user looking for installation instructions will not find a complete pull-and-run tutorial in this README. The README directs users to the Docker Hub page for the `docker` Official Image, where the full usage description is published. It also says that the Docker Hub description is maintained in the `docker-library/docs` repository, specifically under its `docker` directory.

That division is sensible for a generated repository. The local README acts as a short repository entry point and is generated by `generate-repo-stub-readme.sh` according to its final notice. It does not attempt to duplicate the Docker Hub documentation. The practical tutorial available from this source therefore has two steps: use Docker Hub to choose and run the relevant Official Image, and consult the `docker-library/docs` repository when editing the published description.

No image name variant, tag, platform, port, volume, environment variable, or run command is supplied by the README. Inventing those details would make the tutorial misleading, so this article does not provide an example command. Users who need an executable first-use example must consult the linked Docker Hub page and verify that the instructions correspond to the CLI, dind, rootless, or Windows variant they intend to use.

Changes after merge and the official-images workflow

The repository documents a post-merge synchronization issue: a change may be merged into this Git repository without appearing on Docker Hub immediately. For the lifecycle explanation, the README links to the `docker-library/faq` entry titled `An image's source changed in Git, now what?`. This is the relevant source for understanding how source changes move from this repository into the published image.

Outstanding pull requests for the image are handled in a different repository. The README directs users to pull requests carrying the `library/docker` label in `docker-library/official-images`. It further identifies the `library/docker` file in that repository as the current source of truth for the Docker Official Image. That makes this repository important for image implementation, but not the final catalog record used by the official-images workflow.

The distinction can confuse contributors who expect a merged change to be live immediately. A source merge and Docker Hub publication are separate stages. Before treating a change as published, check the lifecycle FAQ and the `library/docker` entry rather than assuming that repository state alone confirms availability on Docker Hub. The README also notes that this repository has no GitHub releases, so GitHub releases are not a useful upgrade signal for this project.

Operational limits of a template repository

The largest limitation is documentation depth. The README names the relevant templates and helper files, but it does not explain how to render them, which host packages are required, which Docker versions are supported, which host architectures are produced, or how to verify a locally built image. It also does not document rollback. This is workable for an established image-maintainer workflow, but it raises the cost for a new contributor who wants to build every variant from the repository alone.

The four visible templates also imply that image selection is not a single decision. A CLI image, a dind image, a rootless dind image, and a Windows Server Core image have different purposes and platform constraints. The README does not identify the exact tags or map each template to a published tag. Using the wrong template would not be defensible from the documentation presented here.

Docker Hub itself is the better fit for a user who only wants to consume the image. A general-purpose Docker installer or a hand-built local Dockerfile is also a different task from maintaining the Official Image packaging. This repository becomes relevant when the requirement is specifically to modify the Docker project's published image definitions, not when the goal is simply to obtain Docker.

Maintenance, upgrades, and the Apache-2.0 boundary

The repository is not archived, and its last push was on 2026-10-14. That supports treating its current source as recently changed, although the README alone does not describe a release cadence. There are no GitHub releases to compare, so upgrades must be understood through source changes and the official-images publication workflow rather than a release-note sequence.

The repository identifies Tianon of the Docker Project as its maintainer. It also separates this packaging source from the published documentation and from the `library/docker` catalog entry. An upgrade review therefore may involve more than editing this repository alone. Contributors should determine whether a change belongs in the image source, the generated documentation, or the official-images record.

The repository is licensed under `Apache-2.0`. That identifies the license associated with the packaging repository, but this review does not interpret the license or provide legal advice. Users should review the repository's `LICENSE` file and the terms associated with Docker Hub separately when evaluating redistribution or compliance requirements.

A practical alternative to editing the Official Image

For ordinary Docker use, Docker Hub is the real alternative because it provides the already packaged `docker` Official Image and points to usage documentation. That approach avoids the unresolved questions in this repository's templates, helper scripts, and generation pipeline. It is appropriate when the requirement is to consume Docker rather than alter the Official Image definition.

For private customization, an organization can maintain its own Docker image instead of changing `docker-library/docker`. That alternative keeps internal policy, additions, and deployment changes outside the upstream Official Image packaging source. However, this repository provides no documented mechanism for extending its templates into an organization-specific image, so the exact implementation cannot be inferred from its README.

The choice is therefore based on ownership. Use Docker Hub for consumption, this repository for upstream Official Image packaging, and a separately owned image for private customization. This repository is the wrong tool when the desired change is merely local configuration or when no one is prepared to work through the official-images and Docker Hub publication lifecycle.

Editorial conclusion

Adopt this repository if you maintain the Docker Official Image packaging and need to change or reproduce its image definitions. Do not treat it as the starting point for learning Docker or installing the Docker CLI, because it provides neither end-user installation instructions nor a direct image build tutorial. Verify first that the Docker Hub documentation still matches the intended image variant, then consult the `library/docker` file in `docker-library/official-images`, which the README identifies as the current source of truth.

Frequently asked questions

Official sources

1. docker-library/docker on GitHub
2. Issues
3. License: Apache-2.0
4. README