docker-kong, the official Kong image and the two-step release dance behind it

This repository builds images, it does not run Kong

The framing matters first. This is the Git repository of the official Docker image for Kong, the image published on Docker Hub under the kong name, and the README points at the Docker Hub page for the full readme on how to use the image and for contributing and issue information. The full readme itself is generated in the docker-library/docs repository, specifically under its kong path, which tells you the division of labour: the usage documentation lives with the docs project, and this repository holds the build. The repository is not archived, the last push was on 2026-10-13, and the recent releases track Kong patch versions: 3.9.4 on 2026-10-13, 3.9.3 on 2026-06-17 and 3.9.2 on 2026-06-04. The primary language recorded for the repository is Shell, which is a good clue about how the work is done, since the moving parts are entrypoint scripts and shell tooling rather than application code.

docker build \
	--no-cache \
	--build-arg ASSET=$(ASSET_LOCATION) \
	$(KONG_VERSION_FLAG) \
	$(KONG_SHA256_FLAG) \
	-t $(DOCKER_TAG) \
	$(BASE)/

A patch release is two pull requests, not one

The process the README describes for Kong developers is the most instructive part of the repository. A patch release in the x.y.Z form can be semi-automated. You check out the repository and run the update script with the version, and it creates a release branch, modifies the relevant files automatically, gives you a chance to review the changes and press y, then pushes the branch and opens a browser with the pull request to this repository. That pull request is reviewed, run through CI and merged. Then you run the submit script with the version and the release flag, and it does the same thing for the official-images repository: it clones Kong's fork, creates a branch, modifies the relevant files automatically, gives you the review and the y prompt, then pushes and opens a browser with the pull request to the docker-library repository. So an image update is a change in two places, and the second one is what actually publishes to Docker Hub.

./update.sh x.y.z

./submit.sh -p x.y.z

Why the publish step lives in another repository

The reason for the two-step dance is the official images process. The README addresses the case that will confuse anyone who merges a change here and then wonders why nothing appeared: it points at the library/kong manifest file in the docker-library/official-images repository, and at the pull requests there carrying the library/kong label, and at the official images readme for how the process works. The manifest is the record of what the official image is supposed to contain, so a change to the Dockerfiles here only becomes a published image once the manifest is updated and that change is merged into official-images. Minor releases are explicitly not semi-automated, and the reason given is that minor releases are more likely to require more extensive changes to the Dockerfiles. That is the honest signal about the workflow: the automation is tuned for the small, frequent case, and the large case is manual by design.

1. Check out this repository.
2. Run `./update.sh x.y.z`
3. Peer review, run CI and merge the submitted PR.
4. Run `./submit.sh -p x.y.z`

Three package formats and two base image styles

The Dockerfile set is where the packaging differences live. There is a Dockerfile.deb, a Dockerfile.rpm and an ubuntu/ directory for the Debian based build, plus a Makefile that switches between them with a PACKAGE variable, defaulting to deb, and a BASE variable, defaulting to ubuntu. The makefile also carries a distinction that is easy to miss. The plain build target builds from the BASE directory, which is the older style where the Dockerfile lives next to its assets. The build_v2 target instead builds with the Dockerfile named after the package format and given a `-f` flag against the repository root, and its default asset location is remote rather than ce. The tags reflect the difference too: without build_v2 in the goals, the tag is prefix-base, and with it, the tag is prefix-package. So kong-ubuntu and kong-deb are two different shapes of image rather than two spellings of the same one.

DOCKER_TAG_PREFIX?=kong
PACKAGE?=deb
BASE?=ubuntu

Version and checksum passed as build arguments

The makefile has a careful pattern for how the Kong version reaches the image, and it is worth reading because it solves a real problem. The KONG_VERSION and KONG_SHA256 variables are passed to docker build as build arguments, but only if they are set. If the variable is empty, the flag variable is left empty, which means the flag is not passed to docker at all rather than being passed with an empty value. The comment explains the reasoning: this way the build-arg flag variables are empty, preventing a flag from being passed to docker at all, if the parent variables are unset, and that in turn preserves the default values from the Dockerfiles. In other words, the Dockerfiles own the default version, and the build only overrides it when a human asks for a specific one. There is also a KONG_BUILD_TOOLS variable with a warning not to update it manually, because it is set by the update script to ensure the same version is used here and in the respective Kong version.

KONG_BUILD_TOOLS?=4.33.19
KONG_VERSION?=
KONG_SHA256?=

The entrypoint, the tests and the local build path

The repository contains a docker-entrypoint.sh, which is the script that runs when the container starts and is where environment variables are turned into a Kong configuration and a start command, and it is the piece to read before you deploy the image, because the behaviour differences between the image variants often live here. Alongside it there is a tests/ directory with a test.sh, and the makefile wires it into a test target that runs the suite with the name Docker-Kong test suite, passing the image tag and base as environment. The build targets are also self-testing in a loose sense, since the v2 build target inspects the image first with docker image inspect and only rebuilds if the tag is missing, which makes repeated builds cheap. The repository also ships a build_your_own_images.md document, and the makefile comment asks that substantial changes to the build be reflected there, dated 2022-06-14. The RHEL release target has its own set of variables, with a registry key, a registry pointing at scan.connect.redhat.com and a repository path built from those two.

test: KONG_DOCKER_TAG?=$(DOCKER_TAG)
test:
	BASE=$(BASE) ./tests/test.sh --suite "Docker-Kong test suite"

Licence, layout and what the repository is not

The licence is Apache-2.0, with the file at the root, and the repository has a.editorconfig, a.gitattributes, a hadolint.yaml for Dockerfile linting and a CI workflow badge. The top level also holds compose/ and customize/ directories, which is where the local Compose setups and the image customization examples live, plus kong-build-tools/, a prebuilt kong.apk.tar.gz, kong.deb and kong.rpm, and an ubuntu/ directory. The last three files are the package artifacts consumed by the Dockerfiles, which is why the build has an ASSET argument with values such as ce for a local asset and remote for a fetched one. What this repository is not is a Kong plugin collection, a configuration repository, or a fork of the gateway. Kong itself lives in its own repository, and this one packages it. The practical consequence for a user is that if you are deciding whether to depend on this project, you are depending on the packaging and the entrypoint, not on any gateway feature.

Dockerfile.deb
Dockerfile.rpm
docker-entrypoint.sh
update.sh
submit.sh

Editorial conclusion

Adopt docker-kong if you need to run Kong Gateway in containers and want the official image rather than one you assemble yourself, and skip it if you are looking for a Kong plugin or configuration source, because this repository contains none of the gateway code. Verify three things before you rely on it: which image variant you pull, since the tag carries both the base and the package format; that you understand the two-step publish, because a change merged here does not appear on Docker Hub until the official-images pull request is merged as well; and that the entrypoint script's behaviour matches your deployment, since it is the piece that turns environment variables into a Kong configuration at start time.

Frequently asked questions

Official sources

1. Kong/docker-kong on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases