nginx/docker-nginx: what the official NGINX Dockerfiles actually build

What nginx/docker-nginx is, and who it is not for

This repository is the build source for the Docker "Official Image" for nginx. The README states it plainly: "This is the Git repo of the Docker 'Official Image' for nginx." The audience is therefore narrow. It is for people who want to understand, audit or contribute to how the published image is assembled, and for maintainers who need to know which template produces which tag. If you only want to run a web server in a container, this repo is the wrong door: the README points to the Docker Hub page for the full readme on how to use the image, and says the image description there is generated and maintained in the docker-library/docs repository, in the nginx directory. The changelog for NGINX itself lives at nginx.org, not here. So the practical split is: usage documentation on Docker Hub, version history on nginx.org, build logic in this repo. Anyone looking for a compose file, a TLS automation helper or a proxy management UI will not find one in these top-level entries.

Templates, generated Dockerfiles and the entrypoint directory

The repository layout is the architecture. Instead of hand-written Dockerfiles, it holds .template files: Dockerfile-alpine.template, Dockerfile-alpine-slim.template, Dockerfile-alpine-perl.template, Dockerfile-alpine-otel.template, Dockerfile-debian.template, Dockerfile-debian-perl.template and Dockerfile-debian-otel.template. The update.sh script is what turns those templates into concrete Dockerfiles, and generate-stackbrew-library.sh produces the library file that the official-images pipeline consumes. The version directories mainline/ and stable/ hold the per-release output, and modules/ holds the additional module definitions. Two other scripts sit at the top level: sync-awsecr.sh, which relates to syncing to AWS ECR, and the entrypoint/ directory, which contains the container entrypoint scripts that ship inside the image. That entrypoint is the piece most users actually touch without knowing it, because it is what processes files dropped into the image's configuration directories at startup. The README does not document the entrypoint's behaviour in detail, so if you need to know exactly how a mounted configuration file is handled, read the scripts in entrypoint/ directly rather than trusting a blog post.

Pulling the image and starting a first container

Because this repository builds an image rather than shipping a binary, installation means pulling from Docker Hub. The README gives no command of its own and defers to the Docker Hub page for usage, so there is no repository-supplied run command to copy here. What the material does establish is the image name: the badges and links throughout the README point at the nginx repository on Docker Hub, and the repository describes itself as the Git repo of the Docker Official Image for nginx. The templates and scripts in this repository are the build inputs, not something an end user executes.

The practical consequence is that the first step is to read the Docker Hub page for nginx, which the README names as the place holding the full readme on how to use the image. Anything beyond that, including which tags exist and how they map to the alpine, debian, perl and otel templates, has to come from the library/nginx file in the docker-library/official-images repository, which the README identifies as the current source of truth for the image. If you need a working command sequence, take it from those two sources rather than from this repository.

Alpine, Debian, perl and otel: choosing a variant

The template names are the variant list, and they are not cosmetic. There is a Debian-based default and an Alpine-based alternative, plus a slim Alpine template, a perl template for each base, and an otel template for each base. The alpine and debian templates differ in base distribution, which changes the package manager, the libc and the size of the resulting layer; the perl variants exist because some deployments need the embedded Perl module; the otel variants are for builds that include OpenTelemetry support. The README does not spell out which tags map to which template, so the mapping has to be read from the generated library file rather than guessed from the repository tree. This is the first real constraint of working from this repo: the template names tell you what kinds of image exist, but the authoritative tag list lives in docker-library/official-images under library/nginx. Multi-architecture support is visible in the README's build badge table, which lists amd64, arm32v5, arm32v6, arm32v7, arm64v8, i386, mips64le, ppc64le and s390x. If you are targeting an unusual platform, that table is the first thing to check, not the last.

Where this repository will not help you

The most common mismatch is expecting this repo to be a deployment toolkit. It is not. There is no compose file, no certbot or letsencrypt integration, no reverse proxy manager, and no PHP-FPM wiring in the top-level entries. Those are all things people search for alongside the nginx image, and all of them have to come from somewhere else. The README is explicit that issues and usage questions belong on the Docker Hub page and that support is community-based, with a SUPPORT.md and a community forum linked from the badges. A second limitation is release cadence as seen from this repository: the listed releases are 1.19.4 from 2020-11-10 and 1.17.2 from 2019-07-31, which do not reflect the image tags currently published. The last push to the repository was on 2026-09-21, so the build machinery is being touched, but the releases list is not a reliable way to track NGINX versions. Use the nginx.org changes page for that, as the README directs.

nginx/docker-nginx compared with running NGINX from a distribution package

The real alternative is not another container project; it is installing NGINX natively from your distribution's package manager. The difference in approach is who owns the configuration lifecycle. With a native package, the distribution maintainer decides the compiled-in modules, the default configuration layout under /etc/nginx, and the upgrade path through the package manager. With the official image built from this repository, NGINX Docker Maintainers own the build, the templates decide the module set per variant, and your upgrade path is a tag change plus a container restart. The container route gives you the same NGINX binary with a reproducible base and a documented multi-arch matrix; the native route gives you the distribution's security patching and its init integration without a container runtime. Neither is strictly better. If your host already has a configuration management story tied to /etc/nginx and systemd, adding a container layer means maintaining two configuration sources. If you need the alpine, perl or otel variant specifically, the native package almost certainly will not give you that combination. The other comparison people draw is against proxy-focused container projects, but those solve a different problem: they generate configuration for you, while this repository only builds the server that reads it.

Licence and the cost of tracking upstream

The repository is BSD-2-Clause, and the README carries an F5, Inc. copyright notice covering 2014 to 2025. That licence applies to the Dockerfiles and scripts in this repository. It does not automatically describe the NGINX binary or the base distribution images layered underneath, which carry their own terms; if you redistribute a derived image, check each layer rather than assuming the repository licence covers the whole artifact. On upgrade cost, the structure is the good news: because Dockerfiles are generated from templates by update.sh, a new NGINX release is a template change plus regeneration rather than a hand-edit of seven files. The cost lands on you at the tag level. Pinning to a specific version means you decide when to move, and you inherit the job of watching nginx.org's changes page for security fixes. Tracking a floating tag inverts that: less work, less control over when the underlying version shifts. The README does not document a rollback procedure for a bad tag, so a digest pin in your own deployment tooling is the practical way to keep that option open.

Editorial conclusion

Adopt the official nginx image when you want a predictable base that the NGINX Docker Maintainers build from this repository, and read the Docker Hub page rather than this repo for usage. Do not treat nginx/docker-nginx as a configuration framework: it ships no compose file, no certbot integration and no reverse proxy manager UI, so those jobs belong to other projects. Before relying on a tag, check the library/nginx file in docker-library/official-images for the digest it currently points to, and confirm whether you need the alpine, perl or otel variant rather than the default.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-2-Clause
3. nginx/docker-nginx on GitHub
4. README
5. Releases