official-images Documentation

1. Project Overview & Quickstart (docker-library/official-images) Copy Chapter

Docker Official Images

Table of Contents Copy Chapter

1. Docker Official Images
   1. Table of Contents
   2. What are "Official Images"?
   3. Architectures other than amd64?
   4. More FAQs?
   5. Contributing to the standard library
   text Copy

   1.    [Review Guidelines](#review-guidelines)
       1.    [Maintainership](#maintainership)
       2.    [Repeatability](#repeatability)
       3.    [Consistency](#consistency)
       4.    [Clarity](#clarity)
       5.    [init](#init)
       6.    [Cacheability](#cacheability)
       7.    [Security](#security)
           1.    [Image Build](#image-build)
           2.    [Runtime Configuration](#runtime-configuration)
           3.    [Security Releases](#security-releases)
       8.    [Multiple Architectures](#multiple-architectures)
   2.    [Commitment](#commitment)

   6. Library definition files
   text Copy

   1.    [Filenames](#filenames)
   2.    [Tags and aliases](#tags-and-aliases)
   3.    [Instruction format](#instruction-format)
   4.    [Creating a new repository](#creating-a-new-repository)
   5.    [Adding a new tag in an existing repository (that you're the maintainer of)](#adding-a-new-tag-in-an-existing-repository-that-youre-the-maintainer-of)
   6.    [Change to a tag in an existing repository (that you're the maintainer of)](#change-to-a-tag-in-an-existing-repository-that-youre-the-maintainer-of)

   7. Bashbrew

What are "Official Images"? Copy Chapter

The Docker Official Images are curated images hosted on Docker Hub. The main tenets are:

• Focus on Free and Open-Source Software

• Support multiple architectures

• Exemplify Dockerfile best practices

• Actively rebuild for updates and security fixes

• Adhere to upstream recommendations

• Add minimal quality-of-life behavior for the container environment where fit

See Docker's documentation for a good high-level overview of the program.

In essence we strive to heed upstream's recommendations on how they intend for their software to be consumed. Many images are maintained in collaboration with the relevant upstream project if not maintained directly by them. Additionally we aim to exemplify the best practices for Dockerfiles to serve as a reference when making or deriving your own images from them.

(If you are a representative of an upstream for which there exists an image and you would like to get involved, please see the Maintainership section below!)

Architectures other than amd64? Copy Chapter

Some images have been ported for other architectures, and many of these are officially supported (to various degrees).

• Architectures officially supported by Docker, Inc. for running Docker: (see download.docker.com)
  • ARMv6 32-bit (arm32v6): https://hub.docker.com/u/arm32v6/
  • ARMv7 32-bit (arm32v7): https://hub.docker.com/u/arm32v7/
  • ARMv8 64-bit (arm64v8): https://hub.docker.com/u/arm64v8/
  • Linux x86-64 (amd64): https://hub.docker.com/u/amd64/
  • Windows x86-64 (windows-amd64): https://hub.docker.com/u/winamd64/
• Other architectures built by official images: (but not officially supported by Docker, Inc.)
  • ARMv5 32-bit (arm32v5): https://hub.docker.com/u/arm32v5/
  • IBM POWER8 (ppc64le): https://hub.docker.com/u/ppc64le/
  • IBM z Systems (s390x): https://hub.docker.com/u/s390x/
  • RISC-V 64-bit (riscv64): https://hub.docker.com/u/riscv64/
  • x86/i686 (i386): https://hub.docker.com/u/i386/

These other architectures are included under the non-prefixed images via OCI "image indexes", such that, for example, docker run hello-world should run as-is on all supported platforms.

If you're curious about how these are built, head over to our FAQ entry to see an explanation of the process or visit meta-scripts to see the build process source files.

See the multi-arch section below for recommendations in adding more architectures to an official image.

More FAQs? Copy Chapter

Yes! We have a dedicated FAQ repository where we try to collect other common questions (both about the program and about our practices).

Contributing to the standard library Copy Chapter

Thank you for your interest in the Docker official images project! We strive to make these instructions as simple and straightforward as possible, but if you find yourself lost, don't hesitate to seek us out on Libera.Chat IRC in channel #docker-library or by creating a GitHub issue here.

Be sure to familiarize yourself with Official Repositories on Docker Hub and the Best practices for writing Dockerfiles in the Docker documentation. These will be the foundation of the review process performed by the official images maintainers. If you'd like the review process to go more smoothly, please ensure that your Dockerfiles adhere to all the points mentioned there, as well as below, before submitting a pull request.

Also, the Hub descriptions for these images are currently stored separately in the docker-library/docs repository, whose README.md file explains more about how it's structured and how to contribute to it. Please be prepared to submit a PR there as well, pending acceptance of your image here.

Review Guidelines Copy Section

Because the official images are intended to be learning tools for those new to Docker as well as the base images for advanced users to build their production releases, we review each proposed Dockerfile to ensure that it meets a minimum standard for quality and maintainability. While some of that standard is hard to define (due to subjectivity), as much as possible is defined here, while also adhering to the "Best Practices" where appropriate.

A checklist which may be used by the maintainers during review can be found in NEW-IMAGE-CHECKLIST.md.

Maintainership

Version bumps and security fixes should be attended to in a timely manner.

If you do not represent upstream and upstream becomes interested in maintaining the image, steps should be taken to ensure a smooth transition of image maintainership over to upstream.

For upstreams interested in taking over maintainership of an existing repository, the first step is to get involved in the existing repository. Making comments on issues, proposing changes, and making yourself known within the "image community" (even if that "community" is just the current maintainer) are all important places to start to ensure that the transition is unsurprising to existing contributors and users.

When taking over an existing repository, please ensure that the entire Git history of the original repository is kept in the new upstream-maintained repository to make sure the review process isn't stalled during the transition. This is most easily accomplished by forking the new from the existing repository, but can also be accomplished by fetching the commits directly from the original and pushing them into the new repo (ie, git fetch https://github.com/jsmith/example.git master, git rebase FETCH_HEAD, git push -f). On GitHub, an alternative is to move ownership of the git repository. This can be accomplished without giving either group admin access to the other owner's repository:

• create temporary intermediary organization
  • docker-library-transitioner is available for this purpose if you would like our help
• give old and new owners admin access to intermediary organization
• old owner transfers repo ownership to intermediary organization
• new owner transfers repo ownership to its new home
  • recommend that old owner does not fork new repo back into the old organization to ensure that GitHub redirects will just work

Repeatability

Rebuilding the same Dockerfile should result in the same version of the image being packaged, even if the second build happens several versions later, or the build should fail outright, such that an inadvertent rebuild of a Dockerfile tagged as 0.1.0 doesn't end up containing 0.2.3. For example, if using apt to install the main program for the image, be sure to pin it to a specific version (ex: ... apt-get install -y my-package=0.1.0 ...). For dependent packages installed by apt there is not usually a need to pin them to a version.

No official images can be derived from, or depend on, non-official images (allowing the non-image scratch and the intentionally limited exceptions pinned in .external-pins -- see also .external-pins/list.sh).

Consistency

All official images should provide a consistent interface. A beginning user should be able to docker run official-image bash (or sh) without needing to learn about --entrypoint. It is also nice for advanced users to take advantage of entrypoint, so that they can docker run official-image --arg1 --arg2 without having to specify the binary to execute.

1. If the startup process does not need arguments, just use CMD:

   dockerfile Copy

   CMD ["irb"]

2. If there is initialization that needs to be done on start, like creating the initial database, use an ENTRYPOINT along with CMD:

   dockerfile Copy

   ENTRYPOINT ["/docker-entrypoint.sh"]
   CMD ["postgres"]

   1. Ensure that docker run official-image bash (or sh) works too. The easiest way is to check for the expected command and if it is something else, just exec "$@" (run whatever was passed, properly keeping the arguments escaped).
   text Copy

   ```sh
   #!/bin/sh
   set -e
   
   # this if will check if the first argument is a flag
   # but only works if all arguments require a hyphenated flag
   # -v; -SL; -f arg; etc will work, but not arg1 arg2
   if [ "$#" -eq 0 ] || [ "${1#-}" != "$1" ]; then
       set -- mongod "$@"
   fi
   
   # check for the expected command
   if [ "$1" = 'mongod' ]; then
       # init db stuff....
       # use gosu (or su-exec) to drop to a non-root user
       exec gosu mongod "$@"
   fi
   
   # else default to run whatever the user wanted like "bash" or "sh"
   exec "$@"
   ```

3. If the image only contains the main executable and its linked libraries (ie no shell) then it is fine to use the executable as the ENTRYPOINT, since that is the only thing that can run:

   dockerfile Copy

   ENTRYPOINT ["fully-static-binary"]
   CMD ["--help"]

   The most common indicator of whether this is appropriate is that the image Dockerfile starts with scratch (FROM scratch).

Clarity

Try to make the Dockerfile easy to understand/read. It may be tempting, for the sake of brevity, to put complicated initialization details into a standalone script and merely add a RUN command in the Dockerfile. However, this causes the resulting Dockerfile to be overly opaque, and such Dockerfiles are unlikely to pass review. Instead, it is recommended to put all the commands for initialization into the Dockerfile as appropriate RUN or ENV command combinations. To find good examples, look at the current official images.

Some examples at the time of writing:

• php
• python
• ruby:2.2

init

Following the Docker guidelines it is highly recommended that the resulting image be just one concern per container; predominantly this means just one process per container, so there is no need for a full init system. There are two situations where an init-like process would be helpful for the container. The first being signal handling. If the process launched does not handle SIGTERM by exiting, it will not be killed since it is PID 1 in the container (see "NOTE" at the end of the Foreground section in the docker docs). The second situation would be zombie reaping. If the process spawns child processes and does not properly reap them it will lead to a full process table, which can prevent the whole system from spawning any new processes. For both of these concerns we recommend tini. It is incredibly small, has minimal external dependencies, fills each of these roles, and does only the necessary parts of reaping and signal forwarding.

Be sure to use tini in CMD or ENTRYPOINT as appropriate.

It is best to install tini from a distribution-provided package (ex. apt-get install tini). If tini is not available in your distribution or is too old, here is a snippet of a Dockerfile to add in tini:

# Install tini for signal processing and zombie killing
ENV TINI_VERSION v0.18.0
ENV TINI_SIGN_KEY 595E85A6B1B4779EA4DAAEC70B588DFF0527A9B7
RUN set -eux; \
  wget -O /usr/local/bin/tini "https://github.com/krallin/tini/releases/download/${TINI_VERSION}/tini"; \
  wget -O /usr/local/bin/tini.asc "https://github.com/krallin/tini/releases/download/${TINI_VERSION}/tini.asc"; \
  export GNUPGHOME="$(mktemp -d)"; \
  gpg --batch --keyserver keyserver.ubuntu.com --recv-keys "$TINI_SIGN_KEY"; \
  gpg --batch --verify /usr/local/bin/tini.asc /usr/local/bin/tini; \
  command -v gpgconf && gpgconf --kill all || :; \
  rm -r "$GNUPGHOME" /usr/local/bin/tini.asc; \
  chmod +x /usr/local/bin/tini; \
  tini --version

Cacheability

This is one place that experience ends up trumping documentation for the path to enlightenment, but the following tips might help:

• Avoid COPY/ADD whenever possible, but when necessary, be as specific as possible (ie, COPY one-file.sh /somewhere/ instead of COPY . /somewhere).

  The reason for this is that the cache for COPY instructions considers file mtime changes to be a cache bust, which can make the cache behavior of COPY unpredictable sometimes, especially when .git is part of what needs to be COPYed (for example).

• Ensure that lines which are less likely to change come before lines that are more likely to change (with the caveat that each line should generate an image that still runs successfully without assumptions of later lines).

  For example, the line that contains the software version number (ENV MYSOFTWARE_VERSION 4.2) should come after a line that sets up the APT repository .list file (RUN echo 'deb http://example.com/mysoftware/debian some-suite main' > /etc/apt/sources.list.d/mysoftware.list).

Security

Image Build

The Dockerfile should be written to help mitigate interception attacks during build. Our requirements focus on three main objectives: verifying the source, verifying author, and verifying the content; these are respectively accomplished by the following: using https where possible; importing PGP keys with the full fingerprint in the Dockerfile to check signatures; embedding checksums directly in the Dockerfile. All three should be used when possible. Just https and embedded checksum can be used when no signature is published. As a last resort, just an embedded checksum is acceptable if the site doesn't have https available and no signature.

The purpose in recommending the use of https for downloading needed artifacts is that it ensures that the download is from a trusted source which also happens to make interception much more difficult.

The purpose in recommending PGP signature verification is to ensure that only an authorized user published the given artifact. When importing PGP keys, please use the the keys.openpgp.org service when possible (preferring keyserver.ubuntu.com otherwise). See also the FAQ section on keys and verification.

The purpose in recommending checksum verification is to verify that the artifact is as expected. This ensures that when remote content changes, the Dockerfile also will change and provide a natural docker build cache bust. As a bonus, this also prevents accidentally downloading newer-than-expected artifacts on poorly versioned files.

Below are some examples:

• Preferred: download over https, PGP key full fingerprint import and asc verification, embedded checksum verified.

  dockerfile Copy

  ENV PYTHON_DOWNLOAD_SHA512 (sha512-value-here)
  RUN set -eux; \
      curl -fL "https://www.python.org/ftp/python/$PYTHON_VERSION/Python-$PYTHON_VERSION.tar.xz" -o python.tar.xz; \
      curl -fL "https://www.python.org/ftp/python/$PYTHON_VERSION/Python-$PYTHON_VERSION.tar.xz.asc" -o python.tar.xz.asc; \
      export GNUPGHOME="$(mktemp -d)"; \
  # gpg: key F73C700D: public key "Larry Hastings <[email protected]>" imported
      gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 97FC712E4C024BBEA48A61ED3A5CA953F73C700D; \
      gpg --batch --verify python.tar.xz.asc python.tar.xz; \
      rm -r "$GNUPGHOME" python.tar.xz.asc; \
      echo "$PYTHON_DOWNLOAD_SHA512 *python.tar.xz" | sha512sum --strict --check; \
      # install

• Alternate: full key fingerprint imported to apt which will check signatures and checksums when packages are downloaded and installed.

  dockerfile Copy

  RUN set -eux; \
      key='A4A9406876FCBD3C456770C88C718D3B5072E1F5'; \
      export GNUPGHOME="$(mktemp -d)"; \
      gpg --batch --keyserver keyserver.ubuntu.com --recv-keys "$key"; \
      gpg --batch --armor --export "$key" > /etc/apt/keyrings/mysql.asc; \
      gpgconf --kill all; \
      rm -rf "$GNUPGHOME"; \
      apt-key list > /dev/null
  
  RUN set -eux; \
      echo "deb [ signed-by=/etc/apt/keyrings/mysql.asc ] http://repo.mysql.com/apt/debian/ bookworm mysql-${MYSQL_MAJOR}" > /etc/apt/sources.list.d/mysql.list; \
      apt-get update; \
      apt-get install -y mysql-community-client="${MYSQL_VERSION}" mysql-community-server-core="${MYSQL_VERSION}"; \
      rm -rf /var/lib/apt/lists/*; \
      # ...

  (As a side note, rm -rf /var/lib/apt/lists/* is roughly the opposite of apt-get update -- it ensures that the layer doesn't include the extra ~8MB of APT package list data, and enforces appropriate apt-get update usage.)

• Less Secure Alternate: embed the checksum into the Dockerfile.

  dockerfile Copy

  ENV RUBY_DOWNLOAD_SHA256 (sha256-value-here)
  RUN set -eux; \
      curl -fL -o ruby.tar.gz "https://cache.ruby-lang.org/pub/ruby/$RUBY_MAJOR/ruby-$RUBY_VERSION.tar.gz"; \
      echo "$RUBY_DOWNLOAD_SHA256 *ruby.tar.gz" | sha256sum --strict --check; \
      # install

  • Note: the use of either SHA1 or MD5 should be considered a "checksum of last resort" as both are considered generally unsafe:
  text Copy

  -    ["Single-block collision for MD5" from 2012](https://marc-stevens.nl/research/md5-1block-collision/)
  -    ["Announcing the first SHA1 collision" from 2017](https://security.googleblog.com/2017/02/announcing-first-sha1-collision.html)

• Unacceptable: download the file over http(s) with no verification.

  dockerfile Copy

  RUN curl -fL "https://julialang.s3.amazonaws.com/bin/linux/x64/${JULIA_VERSION%[.-]*}/julia-${JULIA_VERSION}-linux-x86_64.tar.gz" | tar ... \
      # install

Runtime Configuration

By default, Docker containers are executed with reduced privileges: whitelisted Linux capabilities, Control Groups, and a default Seccomp profile (1.10+ w/ host support). Software running in a container may require additional privileges in order to function correctly, and there are a number of command line options to customize container execution. See docker run Reference and Seccomp for Docker for reference.

Official Repositories that require additional privileges should specify the minimal set of command line options for the software to function, and may still be rejected if this introduces significant portability or security issues. In general, --privileged is not allowed, but a combination of --cap-add and --device options may be acceptable. Additionally, --volume can be tricky as there are many host filesystem locations that introduce portability/security issues (e.g. X11 socket).

Security Releases

For image updates which constitute a security fix, there are a few things we recommend to help ensure your update is merged, built, and released as quickly as possible:

1. Send an email to [email protected] a few (business) days in advance to give us a heads up and a timing estimate (so we can schedule time for the incoming update appropriately).
2. Include [security] in the title of your pull request (for example, [security] Update FooBar to 1.2.5, 1.3.7, 2.0.1).
3. Keep the pull request free of changes that are unrelated to the security fix -- we'll still be doing review of the update, but it will be expedited so this will help us help you.
4. Be active and responsive to comments on the pull request after it's opened (as usual, but even more so if the timing of the release is of importance).

Multiple Architectures

Each repo can specify multiple architectures for any and all tags. If no architecture is specified, images are built in Linux on amd64 (aka x86-64). To specify more or different architectures, use the Architectures field (comma-delimited list, whitespace is trimmed). Valid architectures are found in Bashbrew's oci-platform.go file:

• amd64
• arm32v6
• arm32v7
• arm64v8
• i386
• ppc64le
• riscv64
• s390x
• windows-amd64

The Architectures of any given tag must be a strict subset of the Architectures of the tag it is FROM.

Images must have a single Dockerfile per entry in the library file that can be used for multiple architectures. This means that each supported architecture will have the same FROM line (e.g. FROM debian:bookworm). See golang, docker, haproxy, and php for examples of library files using one Dockerfile per entry and see their respective git repos for example Dockerfiles.

If different parts of the Dockerfile only happen in one architecture or another, use control flow (e.g.if/case) along with dpkg --print-architecture or apk -print-arch to detect the userspace architecture. Only use uname for architecture detection when more accurate tools cannot be installed. See golang for an example where some architectures require building binaries from the upstream source packages and some merely download the binary release.

For base images like debian it will be necessary to have a different Dockerfile and build context in order to ADD architecture specific binaries and this is a valid exception to the above. Since these images use the same Tags, they need to be in the same entry. Use the architecture specific fields for GitRepo, GitFetch, GitCommit, and Directory, which are the architecture concatenated with hyphen (-) and the field (e.g. arm32v7-GitCommit). Any architecture that does not have an architecture-specific field will use the default field (e.g. no arm32v7-Directory means Directory will be used for arm32v7). See the debian or ubuntu files in the library for examples. The following is an example for hello-world:

Maintainers: Tianon Gravi <[email protected]> (@tianon),
             Joseph Ferguson <[email protected]> (@yosifkit)
GitRepo: https://github.com/docker-library/hello-world.git
GitCommit: 7d0ee592e4ed60e2da9d59331e16ecdcadc1ed87

Tags: latest
Architectures: amd64, arm32v5, arm32v7, arm64v8, ppc64le, s390x
# all the same commit; easy for us to generate this way since they could be different
amd64-GitCommit: 7d0ee592e4ed60e2da9d59331e16ecdcadc1ed87
amd64-Directory: amd64/hello-world
arm32v5-GitCommit: 7d0ee592e4ed60e2da9d59331e16ecdcadc1ed87
arm32v5-Directory: arm32v5/hello-world
arm32v7-GitCommit: 7d0ee592e4ed60e2da9d59331e16ecdcadc1ed87
arm32v7-Directory: arm32v7/hello-world
arm64v8-GitCommit: 7d0ee592e4ed60e2da9d59331e16ecdcadc1ed87
arm64v8-Directory: arm64v8/hello-world
ppc64le-GitCommit: 7d0ee592e4ed60e2da9d59331e16ecdcadc1ed87
ppc64le-Directory: ppc64le/hello-world
s390x-GitCommit: 7d0ee592e4ed60e2da9d59331e16ecdcadc1ed87
s390x-Directory: s390x/hello-world

Tags: nanoserver
Architectures: windows-amd64
# if there is only one architecture, you can use the unprefixed fields
Directory: amd64/hello-world/nanoserver
# or use the prefixed versions
windows-amd64-GitCommit: 7d0ee592e4ed60e2da9d59331e16ecdcadc1ed87
Constraints: nanoserver

See the instruction format section for more information on the format of the library file.

Commitment Copy Section

Proposing a new official image should not be undertaken lightly. We expect and require a commitment to maintain your image (including and especially timely updates as appropriate, as noted above).

Library definition files Copy Chapter

The library definition files are plain text files found in the library/ directory of the official-images repository. Each library file controls the current "supported" set of image tags that appear on the Docker Hub description. Tags that are removed from a library file do not get removed from the Docker Hub, so that old versions can continue to be available for use, but are not maintained by upstream or the maintainer of the official image. Tags in the library file are only built through an update to that library file or as a result of its base image being updated (ie, an image FROM debian:bookworm would be rebuilt when debian:bookworm is built). Only what is in the library file will be rebuilt when a base has updates.

Given this policy, it is worth clarifying a few cases: backfilled versions, release candidates, and continuous integration builds. When a new repository is proposed, it is common to include some older unsupported versions in the initial pull request with the agreement to remove them right after acceptance. Don't confuse this with a comprehensive historical archive which is not the intention. Another common case where the term "supported" is stretched a bit is with release candidates. A release candidate is really just a naming convention for what are expected to be shorter-lived releases, so they are totally acceptable and encouraged. Unlike a release candidate, continuous integration builds which have a fully automated release cycle based on code commits or a regular schedule are not appropriate.

It is highly recommended that you browse some of the existing library/ file contents (and history to get a feel for how they change over time) before creating a new one to become familiar with the prevailing conventions and further help streamline the review process (so that we can focus on content instead of esoteric formatting or tag usage/naming).

Filenames Copy Section

The filename of a definition file will determine the name of the image repository it creates on the Docker Hub. For example, the library/ubuntu file will create tags in the ubuntu repository.

Tags and aliases Copy Section

The tags of a repository should reflect upstream's versions or variations. For example, Ubuntu 14.04 is also known as Ubuntu Trusty Tahr, but often as simply Ubuntu Trusty (especially in usage), so ubuntu:14.04 (version number) and ubuntu:trusty (version name) are appropriate aliases for the same image contents. In Docker, the latest tag is a special case, but it's a bit of a misnomer; latest really is the "default" tag. When one does docker run xyz, Docker interprets that to mean docker run xyz:latest. Given that background, no other tag ever contains the string latest, since it's not something users are expected or encouraged to actually type out (ie, xyz:latest should really be used as simply xyz). Put another way, having an alias for the "highest 2.2-series release of XYZ" should be xyz:2.2, not xyz:2.2-latest. Similarly, if there is an Alpine variant of xyz:latest, it should be aliased as xyz:alpine, not xyz:alpine-latest or xyz:latest-alpine.

It is strongly encouraged that version number tags be given aliases which make it easy for the user to stay on the "most recent" release of a particular series. For example, given currently supported XYZ Software versions of 2.3.7 and 2.2.4, suggested aliases would be Tags: 2.3.7, 2.3, 2, latest and Tags: 2.2.4, 2.2, respectively. In this example, the user can use xyz:2.2 to easily use the most recent patch release of the 2.2 series, or xyz:2 if less granularity is needed (Python is a good example of where that's most obviously useful -- python:2 and python:3 are very different, and can be thought of as the latest tag for each of the major release tracks of Python).

As described above, latest is really "default", so the image that it is an alias for should reflect which version or variation of the software users should use if they do not know or do not care which version they use. Using Ubuntu as an example, ubuntu:latest points to the most recent LTS release, given that it is what the majority of users should be using if they know they want Ubuntu but do not know or care which version (especially considering it will be the most "stable" and well-supported release at any given time).

Instruction format Copy Section

The manifest file format is officially based on RFC 2822, and as such should be familiar to folks who are already familiar with the "headers" of many popular internet protocols/formats such as HTTP or email.

The primary additions are inspired by the way Debian commonly uses 2822 -- namely, lines starting with # are ignored and "entries" are separated by a blank line.

The first entry is the "global" metadata for the image. The only required field in the global entry is Maintainers, whose value is comma-separated in the format of Name (@github) or Name (@github). Any field specified in the global entry will be the default for the rest of the entries and can be overridden in an individual entry.

# this is a comment and will be ignored
Maintainers: John Smith <[email protected]> (@example-jsmith),
             Anne Smith <[email protected]> (@example-asmith)
GitRepo: https://github.com/example/docker-example.git
GitCommit: deadbeefdeadbeefdeadbeefdeadbeefdeadbeef

# this is also a comment, and will also be ignored

Tags: 1.2.3, 1.2, 1, latest
Directory: 1

Tags: 2.0-rc1, 2.0-rc, 2-rc, rc
GitRepo: https://github.com/example/docker-example-rc.git
GitFetch: refs/heads/2.0-pre-release
GitCommit: beefdeadbeefdeadbeefdeadbeefdeadbeefdead
Directory: 2
File: Dockerfile-to-use

Bashbrew will fetch code out of the Git repository (GitRepo) at the commit specified (GitCommit). If the commit referenced is not available by fetching master of the associated GitRepo, it becomes necessary to supply a value for GitFetch in order to tell Bashbrew what ref to fetch in order to get the commit necessary.

The built image will be tagged as <manifest-filename>:<tag> (ie, library/golang with a Tags value of 1.6, 1, latest will create tags of golang:1.6, golang:1, and golang:latest).

Optionally, if Directory is present, Bashbrew will look for the Dockerfile inside the specified subdirectory instead of at the root (and Directory will be used as the "context" for the build instead of the top-level of the repository). If File is present, the specified filename instead of Dockerfile will be used.

See the multi-arch section for details on how to specify a different GitRepo, GitFetch, GitCommit, or Directory for a specific architecture.

Creating a new repository Copy Section

• Create a new file in the library/ folder. Its name will be the name of your repository on the Hub.
• Add your tag definitions using the appropriate syntax (see above).
• Create a pull request adding the file from your forked repository to this one. Please be sure to add details as to what your repository does.

Adding a new tag in an existing repository (that you're the maintainer of) Copy Section

• Add your tag definition using the instruction format documented above.
• Create a pull request from your Git repository to this one. Please be sure to add details about what's new, if possible.

Change to a tag in an existing repository (that you're the maintainer of) Copy Section

• Update the relevant tag definition using the instruction format documented above.
• Create a pull request from your Git repository to this one. Please be sure to add details about what's changed, if possible.

Bashbrew Copy Chapter

Bashbrew (bashbrew) is a tool for cloning, building, tagging, and pushing the Docker official images. See the Bashbrew README for more information.

2. Official Technical Reference & Guides (docker-library/docs) Copy Chapter

File: README.md Copy Chapter

What is this?

This repository contains the image documentation for each of the Docker Official Images. See docker-library/official-images for more information about the program in general.

All Markdown files here are run through tianon's fork of markdownfmt, and verified as formatted correctly via GitHub Actions.

Table of Contents Copy Chapter

1. What is this?
   1. Table of Contents
2. How do I update an image's docs
3. How do I add a new image's docs
4. Files related to an image's docs
   1. folder ``
   2. README.md
   3. content.md
   4. get-help.md
   5. github-repo
   6. license.md
   7. logo.png
   8. maintainer.md
   9. metadata.json
   10. README-short.txt
   11. compose.yaml
5. Files for main Docs repo
   1. update.sh
   2. markdownfmt.sh and ymlfmt.sh
   3. .template-helpers/generate-dockerfile-links-partial.sh
   4. .template-helpers/
6. Scripts unrelated to templates
   1. generate-repo-stub-readme.sh
   2. push.pl and push.sh
7. Issues and Contributing

How do I update an image's docs

Edit the content.md for an image; not the README.md as it's auto-generated from the contents of the other files in that repo. To see the changes to the README.md, run ./update.sh myimage from the repo root, but do not add the README.md changes to your pull request. See also markdownfmt.sh point below.

After opening your Pull Request the changes will be checked by an automated markdownfmt.sh before it can be merged. A common issue is incorrect spacing such as with two lines missing an empty line between them (double-spaced).

How do I add a new image's docs

• Create a folder for my image: mkdir myimage
• Create a README-short.txt (required, 100 char max)
• Create a content.md (required)
• Create a license.md (required)
• Create a maintainer.md (required)
• Create a github-repo (required)
• Create a metadata.json (required)
• Add a logo.png (recommended)

Optionally:

• Run ./markdownfmt.sh -l myimage to list any files that are non-compliant to tianon/markdownfmt.
  Any files in the list will result in a failed build during continuous integration.
  • run ./markdownfmt.sh -d myimage to see a diff of changes required to pass.
• Run ./update.sh myimage to generate myimage/README.md for manual review of the generated copy.
  Note: do not actually commit the README.md file; it is automatically generated/committed before being uploaded to Docker Hub.

Files related to an image's docs

folder `` Copy Chapter

This is where all the partial (e.g. content.md) and generated files (e.g. README.md) for a given image reside, (e.g. golang/). It must match the name of the image used in docker-library/official-images.

`README.md` Copy Chapter

This file is generated using update.sh. Do not commit or edit this file; it is regenerated periodically by a bot.

`content.md` Copy Chapter

This file contains the main content of your image's long description. The basic parts you should have are a "What Is" section and a "How To" section. The following is a basic layout:

# What is XYZ?

// about what the contained software is

%%LOGO%%

# How to use this image

// descriptions and examples of common use cases for the image
// make use of subsections as necessary

`get-help.md` Copy Chapter

This file is an optional override of the default get-help.md. This is the content of the "Where to get help" part of the "Quick reference" at the top of the generated README. We recommend linking to the best places for community support like forums, chat rooms, or mailing lists.

`github-repo` Copy Chapter

This file should contain the URL to the GitHub repository for the Dockerfiles that become the images. The file should be in a single line ending in a newline with no extraneous whitespace. Only one GitHub repo per image repository is supported. It is used in generating links. Here is an example for golang:

https://github.com/docker-library/golang

`license.md` Copy Chapter

This file should contain a link to the license for the main software in the image. Here is an example for golang:

View [license information](http://golang.org/LICENSE) for the software contained in this image.

`logo.png` Copy Chapter

Logo for the contained software. While there are not hard rules on formatting, most existing logos are square or landscape and stay within a few hundred pixels of width. Alternatively, a logo.svg can be used instead, but only one logo file will apply. To use it within content.md, put %%LOGO%% as shown above in the basic content.md layout.

The image is automatically scaled to a 120 pixel square for the top of the Docker Hub page and Hub search results.

`maintainer.md` Copy Chapter

This file should contain a link to the maintainers of the Dockerfile.

`metadata.json` Copy Chapter

This file contains data about the repo for Docker Hub. The minimum file is defined below. ./metadata.sh [repo-name] must be used to correctly format it (use -w to apply its suggested format changes). Only three sorted unique Docker Hub categories are allowed. metadata.json in the root contains the list of categories to choose from. See descriptions for the categories on the Docker docs site.

{
    "hub": {
         "categories": []
    }
}

`README-short.txt` Copy Chapter

This is the short description for the Docker Hub, limited to 100 characters in a single line.

Go (golang) is a general purpose, higher-level, imperative programming language.

`compose.yaml` Copy Chapter

This optional file contains a small, working Compose file showing off how to use the image. To use the compose.yaml, add %%COMPOSE%% to the content.md and this will embed the YAML.

Other official images may be referenced within the YAML to demonstrate the functionality of the image, but no images external to the Docker Official Images program may be referenced.

Files for main Docs repo

`update.sh` Copy Chapter

This is the main script used to generate the README.md files for each image. The generated file is committed along with the files used to generate it. Accepted arguments are which image(s) you want to update or no arguments to update all of them.

This script assumes bashbrew is in your PATH (for scraping relevant tag information from the library manifest file for each repository).

`markdownfmt.sh` and `ymlfmt.sh` Copy Chapter

These two scripts are for verifying the formatting of Markdown (.md) and YAML (.yml) files, respectively. markdownfmt.sh uses the tianon/markdownfmt image and ymlfmt.sh uses the tianon/ymlfmt image.

`.template-helpers/generate-dockerfile-links-partial.sh` Copy Chapter

This script is used by update.sh to create the "Supported tags and respective Dockerfile links" section of each generated README.md from the information in the official-images library/ manifests.

`.template-helpers/` Copy Chapter

The scripts and Markdown files in here are used in building an image's README.md file in combination with its individual files.

Scripts unrelated to templates

`generate-repo-stub-readme.sh` Copy Chapter

This is used to generate a simple README.md to put in the image's repo. We use this in Git repositories within https://github.com/docker-library to simplify our maintenance, but it is not required for anyone else. The only argument is the name of the image (or repo), like golang and it then outputs the readme to standard out.

`push.pl` and `push.sh` Copy Chapter

These are used by us to push the actual content of the READMEs to the Docker Hub as special access is required to modify the Hub description contents. The Dockerfile is used to create a suitable environment for push.pl.

Issues and Contributing

If you would like to make a new Official Image, be sure to follow the guidelines.

Feel free to make a pull request for fixes and improvements to current documentation. For questions or problems on this repo come talk to us via the #docker-library IRC channel on Libera.Chat or open up an issue.

File: adminer/README.md Copy Chapter

Quick reference

• Maintained by:
  Tim Düsterhus (of the Docker Community)

• Where to get help:
  the Docker Community Slack, Server Fault, Unix & Linux, or Stack Overflow

Supported tags and respective `Dockerfile` links

• 6.0.1, 6, latest, 6.0.1-standalone, 6-standalone, standalone

• 6.0.1-fastcgi, 6-fastcgi, fastcgi

• 5.5.1, 5, 5.5.1-standalone, 5-standalone

• 5.5.1-fastcgi, 5-fastcgi

Quick reference (cont.)

• Where to file issues:
  https://github.com/TimWolla/docker-adminer/issues

• Supported architectures: (more info)
  amd64, arm32v6, arm32v7, arm64v8, i386, ppc64le, riscv64, s390x

• Published image artifact details:
  repo-info repo's repos/adminer/ directory (history)
  (image metadata, transfer size, etc)

• Image updates:
  official-images repo's library/adminer label
  official-images repo's library/adminer file (history)

• Source of this description:
  docs repo's adminer/ directory (history)

Adminer

What is Adminer? Copy Chapter

Adminer (formerly phpMinAdmin) is a full-featured database management tool written in PHP. Conversely to phpMyAdmin, it consist of a single file ready to deploy to the target server. Adminer is available for MySQL, PostgreSQL, SQLite, MS SQL, Oracle, Firebird, SimpleDB, Elasticsearch and MongoDB.

adminer.org

How to use this image Copy Chapter

Standalone Copy Section

$ docker run --link some_database:db -p 8080:8080 adminer

Then you can hit http://localhost:8080 or http://host-ip:8080 in your browser.

FastCGI Copy Section

If you are already running a FastCGI capable web server you might prefer running Adminer via FastCGI:

$ docker run --link some_database:db -p 9000:9000 adminer:fastcgi

Then point your web server to port 9000 of the container.

Note: This exposes the FastCGI socket to the Internet. Make sure to add proper firewall rules or use a private Docker network instead to prevent a direct access.

... via [`docker compose`](https://github.com/docker/compose) Copy Section

Example compose.yaml for adminer:

# Use root/example as user/password credentials

services:

  adminer:
    image: adminer
    restart: always
    ports:
      - 8080:8080

  db:
    image: mysql:5.6
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: example

Run docker compose up, wait for it to initialize completely, and visit http://localhost:8080 or http://host-ip:8080 (as appropriate).

Loading plugins Copy Section

This image bundles all official Adminer plugins. You can find the list of plugins on GitHub: https://github.com/vrana/adminer/tree/master/plugins.

To load plugins you can pass a list of filenames in ADMINER_PLUGINS:

$ docker run --link some_database:db -p 8080:8080 -e ADMINER_PLUGINS='tables-filter tinymce' adminer

If a plugin requires parameters to work correctly instead of adding the plugin to ADMINER_PLUGINS, you need to add a custom file to the container:

$ docker run --link some_database:db -p 8080:8080 -e ADMINER_PLUGINS='login-servers' adminer
Unable to load plugin file "login-servers", because it has required parameters: servers
Create a file "/var/www/html/plugins-enabled/login-servers.php" with the following contents to load the plugin:

<?php
require_once('plugins/login-servers.php');

/** Set supported servers
    * @param array array($domain) or array($domain => $description) or array($category => array())
    * @param string
    */
return new AdminerLoginServers(
    $servers = ???,
    $driver = 'server'
);

To load a custom plugin you can add PHP scripts that return the instance of the plugin object to /var/www/html/plugins-enabled/.

Choosing a design Copy Section

The image bundles all the designs that are available in the source package of adminer. You can find the list of designs on GitHub: https://github.com/vrana/adminer/tree/master/designs.

To use a bundled design you can pass its name in ADMINER_DESIGN:

$ docker run --link some_database:db -p 8080:8080 -e ADMINER_DESIGN='nette' adminer

To use a custom design you can add a file called /var/www/html/adminer.css.

Usage with external server Copy Section

You can specify the default host with the ADMINER_DEFAULT_SERVER environment variable. This is useful if you are connecting to an external server or a docker container named something other than the default db.

docker run -p 8080:8080 -e ADMINER_DEFAULT_SERVER=mysql adminer

Supported Drivers Copy Chapter

While Adminer supports a wide range of database drivers this image only supports the following out of the box:

• MySQL
• PostgreSQL
• SQLite
• SimpleDB
• Elasticsearch

To add support for the other drivers you will need to install the following PHP extensions on top of this image:

• pdo_dblib (MS SQL)
• oci8 (Oracle)
• interbase (Firebird)
• mongodb (MongoDB)

License

View license information for the software contained in this image.

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

Some additional license information which was able to be auto-detected might be found in the repo-info repository's adminer/ directory.

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

File: aerospike/README.md Copy Chapter

Quick reference

• Maintained by:
  Aerospike, Inc.

• Where to get help:
  the Docker Community Slack, Server Fault, Unix & Linux, or Stack Overflow

Supported tags and respective `Dockerfile` links

• ee-8.1.2.4, ee-8.1.2.4_1

• ce-8.1.2.4, ce-8.1.2.4_1

Quick reference (cont.)

• Where to file issues:
  the Aerospike Forums or GitHub

• Supported architectures: (more info)
  amd64, arm64v8

• Published image artifact details:
  repo-info repo's repos/aerospike/ directory (history)
  (image metadata, transfer size, etc)

• Image updates:
  official-images repo's library/aerospike label
  official-images repo's library/aerospike file (history)

• Source of this description:
  docs repo's aerospike/ directory (history)

Aerospike Database Docker Images

What is Aerospike? Copy Chapter

Aerospike is a distributed NoSQL database purposefully designed for high performance web scale applications. Aerospike supports key-value and document data models, and has multiple data types including List, Map, HyperLogLog, GeoJSON, and Blob. Aerospike's patented hybrid memory architecture delivers predictable high performance at scale and high data density per node.

Getting Started Copy Chapter

Aerospike Enterprise Edition requires a feature key file to start and to ungate certain features in the database, such as compression. Enterprise customers can use their production or development keys.

Anyone can sign up to get an evaluation feature key file for a full-featured, single-node Aerospike Enterprise Edition.

Aerospike Community Edition supports the same developer APIs as Aerospike Enterprise Edition, and differs in ease of operation and enterprise features. See the product matrix for more.

Running an Aerospike EE node with a feature key file in a mapped directory Copy Section

docker run -d -v DIR:/opt/aerospike/etc/ -e "FEATURE_KEY_FILE=/opt/aerospike/etc/features.conf" --name aerospike -p 3000-3002:3000-3002 aerospike:ee-[version]

Above, DIR is a directory on your machine where you drop your feature key file. Make sure Docker Desktop has file sharing permission to bind mount it into Docker containers.

Running a node with a feature key file in an environment variable Copy Section

FEATKEY=$(base64 ~/Desktop/evaluation-features.conf)
docker run -d -e "FEATURES=$FEATKEY" -e "FEATURE_KEY_FILE=env-b64:FEATURES" --name aerospike -p 3000-3002:3000-3002 aerospike:ee-[version]

Running an Aerospike CE node Copy Section

docker run -d --name aerospike -p 3000-3002:3000-3002 aerospike:ce-[version]

Advanced Configuration Copy Chapter

The Aerospike Docker image has a default configuration file template that can be populated with individual configuration parameters, as we did before with FEATURE_KEY_FILE. Alternatively, it can be replaced with a custom configuration file.

The following sections describe both advanced options.

Injecting configuration parameters Copy Section

You can inject parameters into the configuration template using container-side environment variables with the -e flag.

For example, to set the default namespace name to demo:

docker run -d --name aerospike -e "NAMESPACE=demo" -p 3000-3002:3000-3002 -v /my/dir:/opt/aerospike/etc/ -e "FEATURE_KEY_FILE=/opt/aerospike/etc/features.conf" aerospike:ee-[version]

Injecting configuration parameters into the configuration template isn't compatible with using a custom configuration file. You can use one or the other.

List of template variables

• FEATURE_KEY_FILE - the feature_key_file is only required for the EE image. Default: /etc/aerospike/features.conf
• SERVICE_THREADS - the service_threads. Default: Number of vCPUs
• LOGFILE - the file param of the logging context. Default: /dev/null, do not log to file, log to stdout
• SERVICE_ADDRESS - the bind address of the networking.service subcontext. Default: any
• SERVICE_PORT - the port of the networking.service subcontext. Default: 3000
• HB_ADDRESS - the networking.heartbeat address for cross cluster mesh. Default: any
• HB_PORT - the port for networking.heartbeat communications. Default: 3002
• FABRIC_ADDRESS - the address of the networking.fabric subcontext. Default: any
• FABRIC_PORT - the port of the networking.fabric subcontext. Default: 3001

The single preconfigured namespace is in-memory with filesystem persistence

• NAMESPACE - the name of the namespace. Default: test
• REPL_FACTOR - the namespace replication-factor. Default: 2
• MEM_GB - the namespace memory-size. Default: 1, the unit is always G (GB)
• DEFAULT_TTL - the namespace default-ttl. Default: 30d
• STORAGE_GB - the namespace persistence file size. Default: 4, the unit is always G (GB)
• NSUP_PERIOD - the namespace nsup-period. Default: 120 , nsup-period in seconds

Using a custom configuration file Copy Section

You can override the use of the configuration file template by providing your own aerospike.conf, as described in Configuring Aerospike Database.

You should first -v map a local directory, which Docker will bind mount. Next, drop your aerospike.conf file into this directory. Finally, use the --config-file option to tell Aerospike where in the container the configuration file is (the default path is /etc/aerospike/aerospike.conf). Remember that the feature key file is required, so use feature-key-file in your config file to point to a mounted path (such as /opt/aerospike/etc/feature.conf).

For example:

docker run -d -v /opt/aerospike/etc/:/opt/aerospike/etc/ --name aerospike -p 3000-3002:3000-3002 aerospike:ee-[version] --config-file /opt/aerospike/etc/aerospike.conf

Persistent Data Directory Copy Section

With Docker, the files within the container are not persisted past the life of the container. To persist data, you will want to mount a directory from the host to the container's /opt/aerospike/data using the -v option:

For example:

docker run -d  -v /opt/aerospike/data:/opt/aerospike/data  -v /opt/aerospike/etc:/opt/aerospike/etc/ --name aerospike -p 3000-3002:3000-3002 -e "FEATURE_KEY_FILE=/opt/aerospike/etc/features.conf" aerospike:ee-[version]

The example above uses the configuration template, where the single defined namespace is in-memory with file-based persistence. Just mounting the predefined /opt/aerospike/data directory enables the data to be persisted on the host.

Alternatively, a custom configuration file is used with the parameter file set to be a file in the mounted /opt/aerospike/data, such as in the following config snippet:

namespace test {
    # :
    storage-engine device {
        file /opt/aerospike/data/test.dat
        filesize 4G
        data-in-memory true
    }
}

In this example we also mount the data directory in a similar way, using a custom configuration file.

docker run -d -v /opt/aerospike/data:/opt/aerospike/data -v /opt/aerospike/etc/:/opt/aerospike/etc/ --name aerospike -p 3000-3002:3000-3002 aerospike:ee-[version] --config-file /opt/aerospike/etc/aerospike.conf

Block Storage Copy Section

Docker provides an ability to expose a host's block devices to a running container. The --device option can be used to map a host block device within a container.

Update the storage-engine device section of the namespace in the custom aerospike configuration file.

namespace test {
    # :
    storage-engine device {
        device /dev/xvdc
            write-block-size 128k
    }
}

Now to map a host drive /dev/sdc to /dev/xvdc on a container

docker run -d --device '/dev/sdc:/dev/xvdc' -v /opt/aerospike/etc/:/opt/aerospike/etc/ --name aerospike -p 3000-3002:3000-3002 aerospike:ee-[version] --config-file /opt/aerospike/etc/aerospike.conf

Persistent Lua Cache Copy Section

Upon restart, your lua cache will become emptied. To persist the cache, you will want to mount a directory from the host to the container's /opt/aerospike/usr/udf/lua using the -v option:

docker run -d -v /opt/aerospike/lua:/opt/aerospike/usr/udf/lua -v /opt/aerospike/data:/opt/aerospike/data --name aerospike -p 3000-3002:3000-3002 -e "FEATURE_KEY_FILE=/opt/etc/aerospike/features.conf" aerospike:ee-[version]

Clustering Copy Chapter

Developers using the Aerospike EE single-node evaluation, and most others using Docker Desktop on their machine for development, will not need to configure the node for clustering. If you're interested in using clustering and have a feature key file without a single node limit, read the following sections.

Configuring the node's access address Copy Section

In order for the Aerospike node to properly broadcast its address to the cluster and applications, the access-address configuration parameter needs to be set in the configuration file. If it is not set, then the IP address within the container will be used, which is not accessible to other nodes.

network {
        service {
            address any                  # Listening IP Address
            port 3000                    # Listening Port
            access-address 192.168.1.100 # IP Address used by cluster nodes and applications
        }

Mesh Clustering Copy Section

Mesh networking requires setting up links between each node in the cluster. This can be achieved in two ways:

1. Add a configuration for each node in the cluster, as defined in Network Heartbeat Configuration.
2. Use asinfo to send the tip command, to make the node aware of another node, as defined in tip command in asinfo.

For more, see How do I get a 2 nodes Aerospike cluster running quickly in Docker without editing a single file?

Image Versions Copy Chapter

These images are based on ubuntu:24.04.

ee-[version] Copy Section

These tags are for Aerospike EE images, and will require a feature key file, such as the one you get with the single-node EE evaluation, or one associated with a commercial enterprise license agreement.

ce-[version] Copy Section

These tags are for Aerospike CE images, and do not require a feature key file to start. As mentioned above, the developer API for both is the same, but the editions differ in operational features.

Reporting Issues Copy Chapter

If you have any problems with or questions about this image, please post on the Aerospike discussion forum.

Enterprise customers are welcome to participate in the community forum, but can also report issues through the enterprise support system.

Aerospike EE evaluation users can open an issue in aerospike/aerospike-server-enterprise.docker.

Aerospike CE users can open an issue in aerospike/aerospike-server.docker.

License

Copyright 2019-2021 Aerospike, Inc.

If you are using a feature key file you received as part of your commercial enterprise license, you are operating under the Aerospike Master License Agreement.

If you are using the Aerospike Database EE evaluation feature key file, you are operating under the Aerospike Evaluation License Agreement.

If you are using Aerospike Database CE refer to the license information in the aerospike/aerospike-server repository.

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

Some additional license information which was able to be auto-detected might be found in the repo-info repository's aerospike/ directory.

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

File: almalinux/README.md Copy Chapter

Quick reference

• Maintained by:
  The AlmaLinux OS Foundation

• Where to get help:
  the Docker Community Slack, Server Fault, Unix & Linux, or Stack Overflow

Supported tags and respective `Dockerfile` links

• 10-kitten, 10-kitten-20260602

• 10-kitten-minimal, 10-kitten-minimal-20260602

• latest, 10, 10.2, 10.2-20260602

• minimal, 10-minimal, 10.2-minimal, 10.2-minimal-20260602

• 8, 8.10, 8.10-20260602

• 8-minimal, 8.10-minimal, 8.10-minimal-20260602

• 9, 9.8, 9.8-20260602

• 9-minimal, 9.8-minimal, 9.8-minimal-20260602

Quick reference (cont.)

• Where to file issues:
  https://bugs.almalinux.org or GitHub

• Supported architectures: (more info)
  amd64, arm64v8, i386, ppc64le, riscv64, s390x

• Published image artifact details:
  repo-info repo's repos/almalinux/ directory (history)
  (image metadata, transfer size, etc)

• Image updates:
  official-images repo's library/almalinux label
  official-images repo's library/almalinux file (history)

• Source of this description:
  docs repo's almalinux/ directory (history)

AlmaLinux OS

AlmaLinux OS is an Open Source and forever-free enterprise Linux distribution, governed and driven by the community, focused on long-term stability and a robust production-grade platform. AlmaLinux OS is binary compatible with RHEL®, and it was founded by the team behind the well-established CloudLinux OS. Today, the AlmaLinux OS Foundation, run by a community-elected board of directors, owns and manages the operating system.

About this image

Platform image Copy Chapter

The default (platform) image is a general-purpose image with a full DNF stack and basic tools like find, tar, vi, etc.

The almalinux:latest tag will always point to the latest stable release of the default image. Major releases and minor releases are also tagged with their version (e.g. almalinux:8 or almalinux:8.4).

Minimal image Copy Chapter

The minimal image is a stripped-down image that uses the microdnf package manager and contains a very limited package set. It is designed for applications that come with their own dependencies bundled (e.g. NodeJS, Python).

The almalinux:minimal tag always points to the most recent version of the minimal image. Tags for major (e.g. almalinux:8-minimal) and minor (e.g. almalinux:8.4-minimal) releases are also available.

Upgrade policy Copy Section

All images for supported releases will be updated monthly or as needed for security fixes.

How It's Made Copy Chapter

The rootfs tarballs for this image are built using the livemedia-creator tool. The build script and kickstart files are available in the AlmaLinux/docker-images git repository.

License

View license information for the software contained in this image.

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

Some additional license information which was able to be auto-detected might be found in the repo-info repository's almalinux/ directory.

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

File: alpine/README.md Copy Chapter

Quick reference

• Maintained by:
  Natanael Copa (an Alpine Linux maintainer)

• Where to get help:
  the Docker Community Slack, Server Fault, Unix & Linux, or Stack Overflow

Supported tags and respective `Dockerfile` links

• 20260805, edge

• 3.24.1, 3.24, 3, latest

• 3.23.5, 3.23

• 3.22.5, 3.22

• 3.21.7, 3.21

Quick reference (cont.)

• Where to file issues:
  https://github.com/alpinelinux/docker-alpine/issues

• Supported architectures: (more info)
  amd64, arm32v6, arm32v7, arm64v8, i386, ppc64le, riscv64, s390x

• Published image artifact details:
  repo-info repo's repos/alpine/ directory (history)
  (image metadata, transfer size, etc)

• Image updates:
  official-images repo's library/alpine label
  official-images repo's library/alpine file (history)

• Source of this description:
  docs repo's alpine/ directory (history)

What is Alpine Linux?

Alpine Linux is a Linux distribution built around musl libc and BusyBox. The image is only 5 MB in size and has access to a package repository that is much more complete than other BusyBox based images. This makes Alpine Linux a great image base for utilities and even production applications. Read more about Alpine Linux here and you can see how their mantra fits in right at home with Docker images.

How to use this image

Usage Copy Chapter

Use like you would any other base image:

FROM alpine:3.14
RUN apk add --no-cache mysql-client
ENTRYPOINT ["mysql"]

This example has a virtual image size of only 36.8MB. Compare that to our good friend Ubuntu:

FROM ubuntu:20.04
RUN apt-get update \
    && apt-get install -y --no-install-recommends mysql-client \
    && rm -rf /var/lib/apt/lists/*
ENTRYPOINT ["mysql"]

This yields us a virtual image size of about 145MB image.

License

View license information for the software contained in this image.

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

Some additional license information which was able to be auto-detected might be found in the repo-info repository's alpine/ directory.

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

File: alt/README.md Copy Chapter

Quick reference

• Maintained by:
  The ALT Linux Team Cloud

• Where to get help:
  the Docker Community Slack, Server Fault, Unix & Linux, or Stack Overflow

Supported tags and respective `Dockerfile` links

• p10

• sisyphus

• p11, latest

Quick reference (cont.)

• Where to file issues:
  First of all, please, make sure that the developers are not aware of the bug in ALT bugzilla.

For create new bug, please use ALT's bugzilla page (choose Official image as component and include details about image problems in the description) or GitHub.

• Supported architectures: (more info)
  amd64, arm64v8, i386, riscv64

• Published image artifact details:
  repo-info repo's repos/alt/ directory (history)
  (image metadata, transfer size, etc)

• Image updates:
  official-images repo's library/alt label
  official-images repo's library/alt file (history)

• Source of this description:
  docs repo's alt/ directory (history)

ALT Linux

This image serves as the official ALT image for the ALT Linux.

ALT Linux Team

ALT Linux Team is an international community numbering over 200 free software developers.

Sisyphus

Sisyphus is a daily updated repository which serves as a basis for all ALT distributions. Sisyphus integrity supported by the ALT Linux Team, the original software packaging technology, and apt-get (apt-rpm) utility allows users to easily update the system and be aware of any news on the free software. This daily updated repository contains the latest software with all its benefits and pitfalls (latent sometimes).

The name Sisyphus comes from the Greek mythology. Uninterrupted efforts on improvement of technologies set in the repository make ALT Linux Team similar to tireless Sisyphus continuously rolling stones up the hill.

About Platform 9

As said above, Sisyphus is a frequently updated repository mainly designed for developers. Stable distributions by ALT are the best solution for those users preferring stability and predictability of the system to its functionality (primarily new and corporate users). Such stable distributions are based on stable Sisyphus repository slices called platforms. Platform 9 (p9) was created in June, 2019, and will be supported till December, 2022.

About this image

The alt:latest tag will always point the latest stable release (which is, at the time of this writing, alt:p9).

How It's Made Copy Chapter

This image was created with the help of mkimage and hasher tools.

Mkimage is a tool used to create images with Linux kernel from the set Sisyphus-like repository. Mkimage uses a set of Makefiles and shell hooks.

Hasher is a tool used for safe and repeatable packaging in clean and controllable environment. This is achieved through creation of a minimum build environment in chroot, installation of all necessary packaging dependencies there, and packet assembly in the new environment. Every package requires a new build environment.

License

View license information for the software contained in this image.

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

Some additional license information which was able to be auto-detected might be found in the repo-info repository's alt/ directory.

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

File: amazoncorretto/README.md Copy Chapter

Quick reference

• Maintained by:
  the AWS JDK team

• Where to get help:
  the Docker Community Slack, Server Fault, Unix & Linux, or Stack Overflow

Supported tags and respective `Dockerfile` links

• 8-al2, 8u504-al2, 8-al2-full, 8-al2-jdk, 8-al2-generic, 8u504-al2-generic, 8-al2-generic-jdk

• 8-al2023, 8u504-al2023, 8-al2023-jdk, 8, 8-jdk, 8u504, latest

• 8-al2023-jre, 8u504-al2023-jre, 8-jre

• 8-al2-native-jre, 8u504-al2-native-jre

• 8-al2-native-jdk, 8u504-al2-native-jdk

• 8-alpine3.21, 8u504-alpine3.21, 8-alpine3.21-full, 8-alpine3.21-jdk

• 8-alpine3.21-jre, 8u504-alpine3.21-jre

• 8-alpine3.22, 8u504-alpine3.22, 8-alpine3.22-full, 8-alpine3.22-jdk

• 8-alpine3.22-jre, 8u504-alpine3.22-jre

• 8-alpine3.23, 8u504-alpine3.23, 8-alpine3.23-full, 8-alpine3.23-jdk

• 8-alpine3.23-jre, 8u504-alpine3.23-jre

• 8-alpine3.24, 8u504-alpine3.24, 8-alpine3.24-full, 8-alpine3.24-jdk, 8-alpine, 8u504-alpine, 8-alpine-full, 8-alpine-jdk

• 8-alpine3.24-jre, 8u504-alpine3.24-jre, 8-alpine-jre, 8u504-alpine-jre

• 11-al2, 11.0.32-al2, 11-al2-full, 11-al2-jdk, 11-al2-generic, 11.0.32-al2-generic, 11-al2-generic-jdk

• 11-al2023, 11.0.32-al2023, 11-al2023-jdk, 11, 11-jdk, 11.0.32

• 11-al2023-headless, 11.0.32-al2023-headless, 11-headless

• 11-al2023-headful, 11.0.32-al2023-headful, 11-headful

• 11-al2-native-headless, 11.0.32-al2-native-headless

• 11-al2-native-jdk, 11.0.32-al2-native-jdk

• 11-alpine3.21, 11.0.32-alpine3.21, 11-alpine3.21-full, 11-alpine3.21-jdk

• 11-alpine3.22, 11.0.32-alpine3.22, 11-alpine3.22-full, 11-alpine3.22-jdk

• 11-alpine3.23, 11.0.32-alpine3.23, 11-alpine3.23-full, 11-alpine3.23-jdk

• 11-alpine3.24, 11.0.32-alpine3.24, 11-alpine3.24-full, 11-alpine3.24-jdk, 11-alpine, 11.0.32-alpine, 11-alpine-full, 11-alpine-jdk

• 17-al2, 17.0.20-al2, 17-al2-full, 17-al2-jdk, 17-al2-generic, 17.0.20-al2-generic, 17-al2-generic-jdk

• 17-al2023, 17.0.20-al2023, 17-al2023-jdk, 17, 17-jdk, 17.0.20

• 17-al2023-headless, 17.0.20-al2023-headless, 17-headless

• 17-al2023-headful, 17.0.20-al2023-headful, 17-headful

• 17-al2-native-headless, 17.0.20-al2-native-headless

• 17-al2-native-headful, 17.0.20-al2-native-headful

• 17-al2-native-jdk, 17.0.20-al2-native-jdk

• 17-alpine3.21, 17.0.20-alpine3.21, 17-alpine3.21-full, 17-alpine3.21-jdk

• 17-alpine3.22, 17.0.20-alpine3.22, 17-alpine3.22-full, 17-alpine3.22-jdk

• 17-alpine3.23, 17.0.20-alpine3.23, 17-alpine3.23-full, 17-alpine3.23-jdk

• 17-alpine3.24, 17.0.20-alpine3.24, 17-alpine3.24-full, 17-alpine3.24-jdk, 17-alpine, 17.0.20-alpine, 17-alpine-full, 17-alpine-jdk

• 21-al2, 21.0.12-al2, 21-al2-full, 21-al2-jdk, 21-al2-generic, 21.0.12-al2-generic, 21-al2-generic-jdk

• 21-al2023, 21.0.12-al2023, 21-al2023-jdk, 21, 21-jdk, 21.0.12

• 21-al2023-headless, 21.0.12-al2023-headless, 21-headless

• 21-al2023-headful, 21.0.12-al2023-headful, 21-headful

• 21-alpine3.21, 21.0.12-alpine3.21, 21-alpine3.21-full, 21-alpine3.21-jdk

• 21-alpine3.22, 21.0.12-alpine3.22, 21-alpine3.22-full, 21-alpine3.22-jdk

• 21-alpine3.23, 21.0.12-alpine3.23, 21-alpine3.23-full, 21-alpine3.23-jdk

• 21-alpine3.24, 21.0.12-alpine3.24, 21-alpine3.24-full, 21-alpine3.24-jdk, 21-alpine, 21.0.12-alpine, 21-alpine-full, 21-alpine-jdk

• 25-al2023, 25.0.4-al2023, 25-al2023-jdk, 25, 25-jdk, 25.0.4

• 25-al2023-headless, 25.0.4-al2023-headless, 25-headless

• 25-al2023-headful, 25.0.4-al2023-headful, 25-headful

• 25-alpine3.21, 25.0.4-alpine3.21, 25-alpine3.21-full, 25-alpine3.21-jdk

• 25-alpine3.22, 25.0.4-alpine3.22, 25-alpine3.22-full, 25-alpine3.22-jdk

• 25-alpine3.23, 25.0.4-alpine3.23, 25-alpine3.23-full, 25-alpine3.23-jdk

• 25-alpine3.24, 25.0.4-alpine3.24, 25-alpine3.24-full, 25-alpine3.24-jdk, 25-alpine, 25.0.4-alpine, 25-alpine-full, 25-alpine-jdk

• 26-al2023, 26.0.2-al2023, 26-al2023-jdk, 26, 26-jdk, 26.0.2

• 26-al2023-headless, 26.0.2-al2023-headless, 26-headless

• 26-al2023-headful, 26.0.2-al2023-headful, 26-headful

• 26-alpine3.21, 26.0.2-alpine3.21, 26-alpine3.21-full, 26-alpine3.21-jdk

• 26-alpine3.22, 26.0.2-alpine3.22, 26-alpine3.22-full, 26-alpine3.22-jdk

• 26-alpine3.23, 26.0.2-alpine3.23, 26-alpine3.23-full, 26-alpine3.23-jdk

• 26-alpine3.24, 26.0.2-alpine3.24, 26-alpine3.24-full, 26-alpine3.24-jdk, 26-alpine, 26.0.2-alpine, 26-alpine-full, 26-alpine-jdk

Quick reference (cont.)

• Where to file issues:
  https://github.com/corretto/corretto-docker/issues

• Supported architectures: (more info)
  amd64, arm64v8

• Published image artifact details:
  repo-info repo's repos/amazoncorretto/ directory (history)
  (image metadata, transfer size, etc)

• Image updates:
  official-images repo's library/amazoncorretto label
  official-images repo's library/amazoncorretto file (history)

• Source of this description:
  docs repo's amazoncorretto/ directory (history)

What is Amazon Corretto? Copy Section

Corretto is a binary distribution of the Open Java Development Kit (OpenJDK) with long-term support from Amazon. Corretto is certified using the Java Technical Compatibility Kit (TCK) to ensure it meets the Java SE standard and is available on Linux, Windows, and macOS. It includes patches from Amazon that have proven useful in running our own services.

Why should I use Corretto? Copy Section

Corretto is a reliable binary distribution of OpenJDK with the assurance of long-term support provided at no cost to you. Amazon runs Corretto internally on thousands of production services. Every modification we make to Corretto fixes or mitigates a problem we found running OpenJDK. Amazon also plans to apply urgent fixes (including security) when they are available and ready to use, outside of the regular quarterly cycle.

How is Corretto different from OpenJDK? Copy Section

Corretto is a distribution of Open JDK with patches included by Amazon that are not yet integrated in the corresponding OpenJDK update projects. We focus on patches that improve performance or stability in OpenJDK, chosen based on Amazon's observations running large services.

What kinds of patches does Amazon intend to include in Corretto? Copy Section

Patches will include security fixes, performance enhancements (e.g., speeding up frequently used functions), garbage collection scheduling, and preventing out-of-memory situations, as well as improved monitoring, reporting, and thread management.

Is there any cost associated with using Corretto? Copy Section

Corretto is distributed by Amazon under an Open Source license at no cost to you. It is licensed under the terms of the GNU Public License version 2 with the Class Path Exception (GPLv2 with CPE). Amazon does not charge for its use or distribution.

What is included in Corretto's long-term support? Copy Section

Amazon will provide security updates for Corretto 8 until at least June 2023. Updates are planned to be released quarterly. Corretto 11, corresponding to OpenJDK 11, will be available during the first half of 2019. Amazon will support Corretto 11 with quarterly updates until at least August 2024.

Can I use Corretto as a drop-in replacement for other JDKs? Copy Section

Corretto is designed as a drop-in replacement for all Java SE distributions unless you are using features (e.g., Java Flight Recorder) not available in OpenJDK. Once Corretto binaries are installed on a host and correctly invoked to run your Java applications (e.g., using the alternatives command on Linux), existing command-line options, tuning parameters, monitoring, and anything else in place will continue to work as before.

Why does security scanner show that a docker image has a CVE? Copy Section

If a security scanner reports that an amazoncorretto image includes a CVE, the first recommended action is to pull an updated version of this image.

If no updated image is available, run the appropriate command to update packages for the platform, ie. run "apk -U upgrade" for Alpine or "yum update -y --security" for AmazonLinux in your Dockerfiles or systems to resolve the issue immediately.

If no updated package is available, please treat this as a potential security issue and follow these instructions or email AWS security directly at [email protected].

It is the responsibility of the base docker image supplier to provide timely security updates to images and packages. The amazoncorretto images are automatically rebuilt when a new base image is made available, but we do not make changes to our Dockerfiles to pull in one-off package updates. If a new base image has not yet been made generally available by a base docker image maintainer, please contact that maintainer to request that the issue be addressed.

Note that there are multiple reasons why a CVE may appear to be present in a docker image, as explained in the docker library FAQs.

Image Variants

The amazoncorretto images come in many flavors, each designed for a specific use case.

`amazoncorretto:` Copy Chapter

This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of.

`amazoncorretto:-alpine` Copy Chapter

This image is based on the popular Alpine Linux project, available in the alpine official image. Alpine Linux is much smaller than most distribution base images (~5MB), and thus leads to much slimmer images in general.

This variant is useful when final image size being as small as possible is your primary concern. The main caveat to note is that it does use musl libc instead of glibc and friends, so software will often run into issues depending on the depth of their libc requirements/assumptions. See this Hacker News comment thread for more discussion of the issues that might arise and some pro/con comparisons of using Alpine-based images.

To minimize image size, it's uncommon for additional related tools (such as git or bash) to be included in Alpine-based images. Using this image as a base, add the things you need in your own Dockerfile (see the alpine image description for examples of how to install packages if you are unfamiliar).

License

Amazon Corretto is released under the same open source license as OpenJDK, which is licensed under the GNU Public License version 2 with the Class Path Exception (GPLv2 with CPE).

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

Some additional license information which was able to be auto-detected might be found in the repo-info repository's amazoncorretto/ directory.

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

File: amazonlinux/README.md Copy Chapter

**DEPRECATION NOTICE**

The 1, 2018.03, and 2018.03.0.20231218.0 tags of this image are EOL (December 31, 2023 / docker-library/official-images#22075, although the last meaningful update was December 18, 2023). Please migrate to amazonlinux:2023. See the AL2023 migration guide for details.

Quick reference

• Maintained by:
  the Amazon Linux Team

• Where to get help:
  the Docker Community Slack, Server Fault, Unix & Linux, or Stack Overflow

Supported tags and respective `Dockerfile` links

• 2023, latest, 2023.12.20260817.0

• 2, 2.0.20260817.0

Quick reference (cont.)

• Where to file issues:

  • amazonlinux/container-images/issues
  • the Amazon Linux forums

• Supported architectures: (more info)
  amd64, arm64v8

• Published image artifact details:
  repo-info repo's repos/amazonlinux/ directory (history)
  (image metadata, transfer size, etc)

• Image updates:
  official-images repo's library/amazonlinux label
  official-images repo's library/amazonlinux file (history)

• Source of this description:
  docs repo's amazonlinux/ directory (history)

What is Amazon Linux? Copy Chapter

Amazon Linux is provided by Amazon Web Services (AWS). It is designed to provide a stable, secure, and high-performance execution environment for applications running on Amazon EC2. The full distribution includes packages that enable easy integration with AWS, including launch configuration tools and many popular AWS libraries and tools. AWS provides ongoing security and maintenance updates to all instances running Amazon Linux.

The Amazon Linux container image contains a minimal set of packages. To install additional packages, use dnf.

Supported major versions of Amazon Linux:

• Amazon Linux 2023 (recommended, latest)

Amazon Linux 2 reached end of life on June 30, 2026 (see AL2 FAQs). Amazon Linux AMI (AL1) reached end of life on December 31, 2023. Please migrate to Amazon Linux 2023.

For information on security updates for Amazon Linux, please refer to:

• Amazon Linux 2023 Security Advisories

Note that Docker Hub's vulnerability scanning for Amazon Linux is currently based on RPM versions, which does not reflect the state of backported patches for vulnerabilities.

What is Amazon Linux 2023? Copy Chapter

• Amazon Linux 2023: https://aws.amazon.com/linux/amazon-linux-2023/
• 2023 Release Notes: https://docs.aws.amazon.com/linux/al2023/release-notes/relnotes.html
• FAQs: https://aws.amazon.com/linux/amazon-linux-2023/faqs/
• What's New: https://aws.amazon.com/about-aws/whats-new/2023/03/amazon-linux-2023/
• User Guide: https://docs.aws.amazon.com/linux/al2023/ug/what-is-amazon-linux.html

Where can I run Amazon Linux container images? Copy Chapter

You can run Amazon Linux container images in any Docker based environment. Examples include, your laptop, in AWS EC2 instances, and ECS clusters.

What packages are available in the Amazon Linux containers? Copy Chapter

Amazon Linux Docker container images contain a subset of the packages in the images for use on EC2 and as VMs in on-premises scenarios. The container images can be configured to use any of the full set of packages in images for EC2 and on-premises use.

Will updates be available for Amazon Linux containers? Copy Chapter

Similar to the Amazon Linux images for AWS EC2 and on-premises use, Amazon Linux container images will get ongoing updates from Amazon in the form of security updates, bug fix updates, and other enhancements. Security bulletins for Amazon Linux are available at https://alas.aws.amazon.com/

What support is available for Amazon Linux outside AWS? Copy Chapter

• GitHub Issues: https://github.com/amazonlinux/amazon-linux-2023/issues
• Documentation: https://docs.aws.amazon.com/linux/
• Paid Support from AWS: https://aws.amazon.com/premiumsupport/

Will AWS support the current versions of Amazon Linux going forward? Copy Chapter

Yes; Amazon Linux 2023 receives ongoing security and maintenance updates. Amazon Linux 2 reached end of life on June 30, 2026, and Amazon Linux AMI (AL1) reached end of life on December 31, 2023. Please migrate to Amazon Linux 2023.

FAQs Copy Chapter

Amazon Linux 2023 Copy Section

• FAQs: https://aws.amazon.com/linux/amazon-linux-2023/faqs/

License

Amazon Linux is available under the GNU General Public License, version 2.0. Individual software packages are available under their own licenses; run rpm -qi [package name] or check /usr/share/doc/[package name]-* and /usr/share/licenses/[package name]-* for details.

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

Some additional license information which was able to be auto-detected might be found in the repo-info repository's amazonlinux/ directory.

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

File: api-firewall/README.md Copy Chapter

Quick reference

• Maintained by:
  The Wallarm Team

• Where to get help:
  the Docker Community Slack, Server Fault, Unix & Linux, or Stack Overflow

Supported tags and respective `Dockerfile` links

• 0.9.6, latest

Quick reference (cont.)

• Where to file issues:
  https://github.com/wallarm/api-firewall/issues

• Supported architectures: (more info)
  amd64, arm64v8, i386

• Published image artifact details:
  repo-info repo's repos/api-firewall/ directory (history)
  (image metadata, transfer size, etc)

• Image updates:
  official-images repo's library/api-firewall label
  official-images repo's library/api-firewall file (history)

• Source of this description:
  docs repo's api-firewall/ directory (history)

What is API Firewall?

Wallarm API Firewall is an open-source light-weighted proxy designed to protect REST API endpoints in cloud-native environments by hardening based on a strict OpenAPI/Swagger schema validation. Wallarm API Firewall relies on a positive security model allowing calls that match a predefined API specification for requests and responses, while rejecting everything else.

The key features of API Firewall are:

• Protect REST API endpoints by blocking requests and responses that do not match the OAS/Swagger schema
• Discover Shadow API endpoints
• If using OAuth 2.0 protocol-based authentication, validate access tokens
• Quick and easy deployment and configuration
• Customization of request and response processing modes, response codes and log format

Use cases

• Block abnormal requests and responses that do not match the OpenAPI 3.0 specification (if running API Firewall in the blocking mode)
• Discover Shadow APIs and undocumented endpoints (if running API Firewall in the logging mode)
• Log abnormal requests and responses that do not match the OpenAPI 3.0 specification (if running API Firewall in the logging mode)

API schema validation and positive security model

When starting API Firewall, you should provide the OpenAPI 3.0 specification of the application to be protected with API Firewall. The started API Firewall will operate as a reverse proxy and validate whether requests and responses match the schema defined in the specification.

The traffic that does not match the schema will be logged using the STDOUT and STDERR Docker services or blocked (depending on the configured API Firewall operation mode). If operating in the logging mode and detecting the traffic on endpoints that are not included in the specification, API Firewall also logs these endpoints as the shadow ones (except for endpoints returning the code 404).

Provided API schema should be described using the OpenAPI 3.0 specification in the YAML or JSON file (.yaml, .yml, .json file extensions).

By allowing you to set the traffic requirements with the OpenAPI 3.0 specification, Wallarm API Firewall relies on a positive security model.

Technical characteristics

API Firewall works as a reverse proxy with a built-in OpenAPI 3.0 request and response validator. The validator is written in Go and optimized for extreme performance and near-zero added latency.

Starting API Firewall

To download, install, and start Wallarm API Firewall on Docker, see the instructions.

Demos

You can try API Firewall by running the demo environment that deploys an example application protected with Wallarm API Firewall. There are two available demo environments:

• Wallarm API Firewall demo with Docker Compose
• Wallarm API Firewall demo with Kubernetes

Wallarm's blog articles related to API Firewall

• Discovering Shadow APIs with API Firewall
• Wallarm API Firewall outperforms NGINX in a production environment

Performance

When creating API Firewall, we prioritized speed and efficiency to ensure that our customers would have the fastest APIs possible. Our latest tests demonstrate that the average time required for API Firewall to process one request is 1.339 ms:

$ ab -c 200 -n 10000 -p ./large.json -T application/json http://127.0.0.1:8282/test/signup

Document Path:          /test/signup
Document Length:        20 bytes

Concurrency Level:      200
Time taken for tests:   0.769 seconds
Complete requests:      10000
Failed requests:        0
Total transferred:      2150000 bytes
Total body sent:        283770000
HTML transferred:       200000 bytes
Requests per second:    13005.81 [#/sec] (mean)
Time per request:       15.378 [ms] (mean)
Time per request:       0.077 [ms] (mean, across all concurrent requests)
Transfer rate:          2730.71 [Kbytes/sec] received
                        360415.95 kb/s sent
                        363146.67 kb/s total

Connection Times (ms)
              min  mean[+/-sd] median   max
Connect:        0    5   1.6      5      12
Processing:     2   10   5.4      9      59
Waiting:        2    8   5.2      7      56
Total:          3   15   5.7     14      68

Percentage of the requests served within a certain time (ms)
  50%     14
  66%     15
  75%     16
  80%     17
  90%     18
  95%     23
  98%     36
  99%     44
 100%     68 (longest request)

These performance results are not the only ones we have got during API Firewall testing. Other results along with the methods used to improve API Firewall performance are described in this Wallarm's blog article.

License

View license information for the software contained in this image.

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

Some additional license information which was able to be auto-detected might be found in the repo-info repository's api-firewall/ directory.

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

File: arangodb/README.md Copy Chapter

Quick reference

• Maintained by:
  ArangoDB

• Where to get help:
  the Docker Community Slack, Server Fault, Unix & Linux, or Stack Overflow

Supported tags and respective `Dockerfile` links

• 3.12, 3.12.10.1, latest

Quick reference (cont.)

• Where to file issues:
  https://github.com/arangodb/arangodb-docker/issues

• Supported architectures: (more info)
  amd64, arm64v8

• Published image artifact details:
  repo-info repo's repos/arangodb/ directory (history)
  (image metadata, transfer size, etc)

• Image updates:
  official-images repo's library/arangodb label
  official-images repo's library/arangodb file (history)

• Source of this description:
  docs repo's arangodb/ directory (history)

What is ArangoDB?

ArangoDB is a scalable graph database system to drive value from connected data, faster. Native graphs, an integrated search engine, and JSON support, via a single query language.

ArangoDB runs everywhere: On-prem, in the cloud, and as a managed cloud service: ArangoGraph Insights Platform.

arangodb.com

Key Features in ArangoDB Copy Chapter

Native Graph Store both data and relationships, for faster queries even with multiple levels of joins and deeper insights that simply aren't possible with traditional relational and document database systems.

Document Store Every node in your graph is a JSON document: flexible, extensible, and easily imported from your existing document database.

ArangoSearch Natively integrated cross-platform indexing, text-search and ranking engine for information retrieval, optimized for speed and memory.

ArangoDB Documentation

• Learn ArangoDB
• Documentation

How to use this image Copy Chapter

Start an ArangoDB instance Copy Section

In order to start an ArangoDB instance, run:

docker run -d -p 8529:8529 -e ARANGO_RANDOM_ROOT_PASSWORD=1 --name arangodb-instance arangodb

Docker chooses the processor architecture for the image that matches your host CPU by default. If this is not the case, for example, because you have the DOCKER_DEFAULT_PLATFORM environment variable set to a different architecture, you can pass the --platform flag to the docker run command to specify the appropriate operating system and architecture for the container. For x86-64, use linux/amd64. On ARM, especially Apple silicon with no emulation for the required AVX instruction set extension, use linux/arm64/v8:

docker run -d -p 8529:8529 -e ARANGO_RANDOM_ROOT_PASSWORD=1 --name arangodb-instance --platform linux/arm64/v8 arangodb

This creates and launches the arangodb Docker instance as a background process. The Identifier of the process is printed. By default, ArangoDB listens on port 8529 for requests.

In order to get the IP ArangoDB listens on, run:

docker inspect --format '{{ .NetworkSettings.IPAddress }}' arangodb-instance

Initialize the server language Copy Section

When using Docker, you need to specify the language you want to initialize the server to on the first run in one of the following ways:

• Set the environment variable LANG to a locale in the docker run command, e.g. -e LANG=sv for a Swedish locale.

• Use an arangod.conf configuration file that sets a language and mount it into the container. For example, create a configuration file on your host system in which you set icu-language = sv at the top (before any [section]) and then mount the file over the default configuration file like docker run -v /your-host-path/arangod.conf:/etc/arangodb3/arangod.conf ....

If you don't specify a language explicitly, the default is en_US up to ArangoDB v3.11 and en_US_POSIX from ArangoDB v3.12 onward.

Using the instance Copy Section

To use the running instance from an application, link the container:

docker run -e ARANGO_RANDOM_ROOT_PASSWORD=1 --name my-app --link arangodb-instance:db-link arangodb

This uses the instance named arangodb-instance and links it into the application container. The application container contains environment variables, which can be used to access the database.

DB_LINK_PORT_8529_TCP=tcp://172.17.0.17:8529
DB_LINK_PORT_8529_TCP_ADDR=172.17.0.17
DB_LINK_PORT_8529_TCP_PORT=8529
DB_LINK_PORT_8529_TCP_PROTO=tcp
DB_LINK_NAME=/naughty_ardinghelli/db-link

Exposing the port to the outside world Copy Section

If you want to expose the port to the outside world, run:

docker run -e ARANGO_RANDOM_ROOT_PASSWORD=1 -p 8529:8529 -d arangodb

ArangoDB listen on port 8529 for request and the image includes EXPOSE 8529. The -p 8529:8529 exposes this port on the host.

Choosing an authentication method Copy Section

The ArangoDB image provides several authentication methods which can be specified via environment variables (-e) when using docker run

1. ARANGO_RANDOM_ROOT_PASSWORD=1

   Generate a random root password when starting. The password will be printed to stdout (may be inspected later using docker logs)

2. ARANGO_NO_AUTH=1

   Disable authentication. Useful for testing.

   WARNING Doing so in production will expose all your data. Make sure that ArangoDB is not directly accessible from the internet!

3. ARANGO_ROOT_PASSWORD=somepassword

   Specify your own root password.

Note: this way of specifying logins only applies to single server installations. With clusters you have to provision the users via the root user with empty password once the system is up.

Command line options Copy Section

You can pass arguments to the ArangoDB server by appending them to the end of the Docker command:

docker run -e ARANGO_RANDOM_ROOT_PASSWORD=1 arangodb --help

The entrypoint script starts the arangod binary by default and forwards your arguments.

You may also start other binaries, such as the ArangoShell:

docker run -it arangodb arangosh --server.database myDB ...

Note that you need to set up networking for containers if arangod runs in one container and you want to access it with arangosh running in another container. It is easier to execute it in the same container instead. Use docker ps to find out the container ID / name of a running container:

docker ps

It prints something similar to the following:

CONTAINER ID   IMAGE     COMMAND                 CREATED      STATUS      PORTS                   NAMES
1234567890ab   arangodb  "/entrypoint.sh aran…"  2 hours ago  Up 2 hours  0.0.0.0:8529->8529/tcp  jolly_joker

Then use docker exec and the ID / name to run something inside of the existing container:

docker exec -it jolly_joker arangosh

For more information, see the ArangoDB documentation about Configuration.

Limiting resource utilization Copy Section

arangod checks the following environment variables, which can be used to restrict how much memory and how many CPU cores it should use:

• ARANGODB_OVERRIDE_DETECTED_TOTAL_MEMORY (introduced in v3.6.3)

  This variable can be used to override the automatic detection of the total amount of RAM present on the system. One can specify a decimal number (in bytes). Furthermore, if G or g is appended, the value is multiplied by 2^30. If M or m is appended, the value is multiplied by 2^20. If K or k is appended, the value is multiplied by 2^10. That is, 64G means 64 gigabytes.

  The total amount of RAM detected is logged as an INFO message at server start. If the variable is set, the overridden value is shown. Various default sizes are calculated based on this value (e.g. RocksDB buffer cache size).

  Setting this option can in particular be useful in two cases:

  1. If arangod is running in a container and its cgroup has a RAM limitation, then one should specify this limitation in this environment variable, since it is currently not automatically detected.
  2. If arangod is running alongside other services on the same machine and thus sharing the RAM with them, one should limit the amount of memory using this environment variable.

• ARANGODB_OVERRIDE_DETECTED_NUMBER_OF_CORES (introduced in v3.7.1)

  This variable can be used to override the automatic detection of the number of CPU cores present on the system.

  The number of CPU cores detected is logged as an INFO message at server start. If the variable is set, the overridden value is shown. Various default values for threading are calculated based on this value.

  Setting this option is useful if arangod is running in a container or alongside other services on the same machine and shall not use all available CPUs.

Persistent Data Copy Chapter

ArangoDB supports two different storage engines from version 3.2 to 3.6. You can choose them while instantiating the container with the environment variable ARANGO_STORAGE_ENGINE. With mmfiles you choose the classic storage engine (not available in 3.7 and later), rocksdb will choose the storage engine based on RocksDB. The default choice is rocksdb from version 3.4 on.

ArangoDB uses the volume /var/lib/arangodb3 as database directory to store the collection data and the volume /var/lib/arangodb3-apps as apps directory to store any extensions. These directories are marked as docker volumes.

See docker inspect --format "{{ .Config.Volumes }}" arangodb for all volumes.

A good explanation about persistence and docker container can be found here: Docker In-depth: Volumes, Why Docker Data Containers are Good

Using host directories Copy Section

You can map the container's volumes to a directory on the host, so that the data is kept between runs of the container. This path /tmp/arangodb is in general not the correct place to store you persistent files - it is just an example!

unix> mkdir /tmp/arangodb
unix> docker run -e ARANGO_RANDOM_ROOT_PASSWORD=1 -p 8529:8529 -d \
        -v /tmp/arangodb:/var/lib/arangodb3 \
        arangodb

This will use the /tmp/arangodb directory of the host as database directory for ArangoDB inside the container.

Using a data container Copy Section

Alternatively you can create a container holding the data.

docker create --name arangodb-persist arangodb true

And use this data container in your ArangoDB container.

docker run -e ARANGO_RANDOM_ROOT_PASSWORD=1 --volumes-from arangodb-persist -p 8529:8529 arangodb

If want to save a few bytes you can alternatively use busybox or alpine for creating the volume only containers. Please note that you need to provide the used volumes in this case. For example

docker run -d --name arangodb-persist -v /var/lib/arangodb3 busybox true

Usage as a base image Copy Section

If you are using the image as a base image please make sure to wrap any CMD in the exec form. Otherwise the default entrypoint will not do its bootstrapping work.

When deriving the image, you can control the instantiation via putting files into /docker-entrypoint-initdb.d/.

• *.sh - files ending with .sh will be run as a bash shellscript.
• *.js - files will be executed with arangosh. You can specify additional arangosh arguments via the ARANGOSH_ARGS environment variable.
• dumps/ - in this directory you can place subdirectories containing database dumps generated using arangodump. They can be restored using arangorestore.

License

The official Docker images of the ArangoDB Community Edition are governed by the ArangoDB Community License. It limits deployments to a 100 GB on dataset size in production and you cannot use it for any commercial purposes, only internal business purposes. It does not include the right to distribute, embed within other products, or combine with ArangoDB's Enterprise Edition of the software.

The source code of the Community Edition is available under the Business Source License 1.1 (BUSL-1.1). Copying, modification, redistribution, non-commercial use, and commercial use in a non-production context are always allowed. Additionally, you can deploy BUSL-licensed ArangoDB source code for any purpose (including production) as long as you are not creating a commercial derivative work or offering, or are including it in a commercial product, application, or service. On the fourth anniversary of the first publicly available distribution of a specific version, the license changes to the permissive Apache 2.0 open-source license.

Up to ArangoDB version 3.11, ArangoDB is licensed under the Apache 2.0 License.

ArangoDB contains software of third parties under their respective licenses.

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

Some additional license information which was able to be auto-detected might be found in the repo-info repository's arangodb/ directory.

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.