docker-library/mongo: how the official MongoDB image is built

One directory per major version, and two platform templates

The top-level layout of the repository is small and entirely mechanical. There are four version directories, `7.0/`, `8.0/`, `8.3/` and `9.0/`, and each of them holds the Dockerfiles for one major release line of MongoDB. Alongside them sit two templates, `Dockerfile-linux.template` and `Dockerfile-windows.template`, which are the inputs from which the per-version Dockerfiles are produced rather than the Dockerfiles themselves.

The supporting scripts are named for their jobs. `apply-templates.sh` is the step that turns a template into concrete files, `update.sh` is the maintenance entry point, and `versions.json` and `versions.sh` together hold the version matrix that tells the update tooling which MongoDB releases exist and which should be built. `pgp-keys.json` and `pgp-keys.sh` handle the GPG key material used to verify the downloaded MongoDB archives, which is the part of a database image build that matters most for supply chain trust, since a database tarball is fetched from the upstream vendor and then executed as the server binary.

Two more files sit in the tree. `generate-stackbrew-library.sh` is another maintenance script in the tree, and `docker-entrypoint.sh` is the entrypoint the image runs.

The whole thing is Apache-2.0 licensed, the default branch is `master`, and the last push was on 2026-10-14, so the packaging is being kept in step with upstream MongoDB releases.

This is not the image MongoDB publishes itself

The distinction the project leads with is easy to miss and matters for anyone filing an issue or looking for the source of a running container.

The repository is the Git source of the Docker Official Image for `mongo`, and it is explicitly not to be confused with any official `mongo` image provided upstream by MongoDB. Those are two different things: an image built by the Docker community from this source, and an image built by the vendor. The README describes this project as maintained by the Docker Community rather than by MongoDB.

The second consequence is where the documentation lives. The full image description on Docker Hub is generated and maintained in the docker-library/docs repository, specifically in the `mongo` directory of that project, and the README in this repository is itself marked as generated by a script from that repository. So the prose a user reads on Docker Hub, including the usage instructions and the environment variables, is authored somewhere else entirely and pulled into this project's published page.

That means this repository is thin on explanation by design. It is a build tree, and the prose about how to use the image is not kept here. Anyone who opens this repository expecting to find usage instructions will find a set of templates and scripts, and the README points them onward to the Docker Hub page for the actual readme.

The official-images file is the source of truth, not this branch

The publishing chain has an authoritative step, and it is not the repository you are reading.

The README names the `library/mongo` file in the docker-library/official-images repository as the current source of truth for the `mongo` image. That file is the declaration of what the image should be, and this repository is the implementation that the official-images build process consumes.

The same division shows up in how pull requests are handled. Outstanding `mongo` image pull requests are tracked as PRs with the `library/mongo` label on the official-images repository, not as PRs against this one. And there is a separate FAQ entry, linked from the README, on what happens when an image's source changes in Git and the change has not yet appeared on Docker Hub, which is the question that comes up every time someone wonders why a tag they just pushed is not yet pullable.

For anyone wanting to make a change, the practical sequence is to understand the templates in this repository, make the change here, and expect the merge to flow through the official-images process before the new image is published. The `library/mongo` file is where the published tag list and build configuration are recorded, so a change that is not reflected there does not become an image.

No releases, no tags to install from, an image that moves under you

The repository has no GitHub releases, which is normal for a Docker Official Image source tree but has a practical consequence for anyone pinning a dependency on it.

There is nothing here to version your build against. What people consume is the published image on Docker Hub, tagged by MongoDB version, and the tags move. A `mongo:8.0` tag is a moving reference to whatever the latest 8.0 build was, and the image content changes over time as the base image is rebuilt, dependencies are refreshed and the upstream tarball is replaced.

That matters most for the MongoDB images because the entrypoint and the base image layer are where a surprising amount of the operational behaviour lives. A container that starts, initialises a data directory, applies authentication settings and then execs `mongod` is a small amount of shell in `docker-entrypoint.sh`, and that shell changes when the build changes.

The pragmatic consequence is that a deployment that cares about reproducibility should not rely on a floating tag, and a deployment that wants to know exactly what changed between two containers should diff the images rather than compare version numbers in the source repository, because there are no version numbers there to compare.

The last push date of 2026-10-14 is the closest thing this repository offers to a version signal, and it says that the packaging was current as of that date, nothing more.

Where this repository is the wrong place to look

There are three common reasons to arrive here and find nothing useful.

The first is looking for MongoDB itself. The server's source, its release notes and its bug tracker are upstream projects, and this repository contains none of that. It contains the container packaging.

The second is looking for how to run the image. The usage instructions, the environment variables for setting up users and the replication configuration are on the Docker Hub page for the `mongo` image, generated from the docker-library/docs repository. They are not here.

The third is looking for the build itself, expecting a plain Dockerfile. The Linux and Windows Dockerfiles are templates, and the actual per-version files are produced by applying those templates, which means reading a template tells you the shape of the image but the runnable file is generated output. A patch applied by hand to a generated Dockerfile is lost on the next update, which is the main practical hazard of working in this tree.

There is also a licensing point worth stating. The packaging in this repository is Apache-2.0, and the build fetches the server binaries from upstream and verifies them against the GPG keys in `pgp-keys.json`.

Compared with building your own MongoDB container

The realistic alternative is to write your own Dockerfile with `FROM mongo` and layer what you need on top, or to build MongoDB from a base image yourself.

The difference in approach is where the work lives. The official image already handles the parts of running a database container that are easy to get subtly wrong: fetching a specific server tarball, verifying it against a pinned GPG key, unpacking it, laying out the directory structure the server expects, and providing an entrypoint that behaves correctly on first start versus on restart, which is where database images most often break. A hand-written `FROM mongo` inherits all of that and adds your layer on top, which is the cheapest path when your needs are modest.

Building MongoDB from scratch, or from a third-party base image, is a different proposition. You get control over the base image, the bundled tools and the exact server build, and you take on the release engineering, the key verification and the entrypoint behaviour that the official image maintains for every upstream release.

What the official image does not give you is a stable interface to pin. The tags move, the build changes, and there is no release history in this repository to consult. A team that wants both convenience and reproducibility has to capture the digest of the image it tested rather than the tag.

The honest summary is that this repository is worth reading if you are packaging MongoDB yourself or need to explain where a running image came from, and worth ignoring if you just need a database. The pull command and its behaviour are documented on the Docker Hub page, not in this tree.

Editorial conclusion

This repository fits someone who needs to understand or change how the official MongoDB container is packaged, for instance to pin a base image, adjust a build step or add a version, and it does not fit someone looking for a MongoDB deployment, since the image, its documentation and its issue tracker all live elsewhere. Before changing anything, read the `library/mongo` file in the docker-library/official-images repository, because that file is the source of truth for what gets published, and check `versions.json` and `versions.sh` to see which major versions this source tree currently carries.

Frequently asked questions

Official sources

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