Skip to content

docker-library/docs

Folders and files

NameName
Last commit message
Last commit date

Latest commit

6b78b6b · Feb 26, 2025
May 17, 2024
Nov 18, 2018
Jul 9, 2024
Jul 5, 2024
Feb 25, 2025
Feb 25, 2025
Feb 4, 2025
Feb 14, 2025
Dec 16, 2024
Jan 24, 2025
Feb 10, 2025
Feb 24, 2025
Feb 14, 2025
Feb 24, 2025
Jan 16, 2025
Feb 25, 2025
Dec 6, 2024
Feb 12, 2025
Feb 25, 2025
Jan 8, 2025
Feb 11, 2025
Jul 8, 2024
Sep 27, 2024
Feb 24, 2025
Jul 29, 2024
Feb 21, 2025
Feb 20, 2025
Jan 21, 2025
Dec 6, 2024
Jan 24, 2025
Oct 22, 2024
Feb 18, 2025
Feb 12, 2025
Feb 25, 2025
Feb 22, 2025
Feb 21, 2025
Oct 22, 2024
Feb 4, 2025
Feb 3, 2025
Feb 25, 2025
Feb 10, 2025
Jan 7, 2025
Feb 24, 2025
Oct 31, 2024
Feb 18, 2025
Feb 3, 2025
Feb 5, 2025
Dec 9, 2024
Aug 1, 2024
Dec 6, 2024
Feb 24, 2025
Feb 25, 2025
Feb 19, 2025
Jan 28, 2025
Feb 21, 2025
Dec 19, 2024
Oct 1, 2024
Jan 22, 2025
May 17, 2024
Jan 24, 2025
Jan 23, 2025
Feb 14, 2025
Feb 18, 2025
Jan 24, 2025
Dec 13, 2024
Jan 15, 2025
Feb 20, 2025
Feb 11, 2025
Jan 23, 2025
Oct 28, 2024
Feb 25, 2025
Dec 20, 2024
Feb 20, 2025
Feb 18, 2025
Feb 25, 2025
Feb 12, 2025
Feb 14, 2025
Jan 24, 2025
Jan 27, 2025
Feb 4, 2025
Feb 22, 2025
Jul 8, 2024
Feb 25, 2025
Dec 6, 2024
Aug 10, 2024
Jan 22, 2025
Feb 25, 2025
Feb 25, 2025
Aug 12, 2024
Feb 26, 2025
Feb 6, 2025
Feb 20, 2025
Jul 8, 2024
Feb 18, 2025
Jan 29, 2025
Feb 22, 2025
Feb 21, 2025
Feb 20, 2025
Jan 8, 2025
Jan 22, 2025
Feb 24, 2025
Jul 29, 2024
Feb 14, 2025
Jan 24, 2025
Aug 19, 2024
Dec 24, 2024
Feb 22, 2025
Feb 13, 2025
Feb 12, 2025
Nov 4, 2024
Feb 13, 2025
Dec 17, 2024
Jan 21, 2025
Feb 1, 2025
Feb 11, 2025
May 17, 2024
Feb 21, 2025
Jul 8, 2024
Jan 28, 2025
Feb 15, 2025
Feb 20, 2025
Jan 28, 2025
Aug 19, 2024
May 17, 2024
Dec 12, 2024
Jan 21, 2025
Feb 7, 2025
Dec 24, 2024
Jan 28, 2025
Jan 28, 2025
Dec 12, 2024
Feb 10, 2025
May 17, 2024
Feb 25, 2025
Feb 19, 2025
Jan 7, 2025
Feb 25, 2025
Feb 4, 2025
Jan 13, 2025
Nov 11, 2024
Jan 29, 2025
Feb 12, 2025
Feb 25, 2025
Jul 8, 2024
Jul 8, 2024
Oct 28, 2024
Aug 7, 2015
Jul 5, 2024
Jul 30, 2018
May 18, 2024
Nov 20, 2024
May 17, 2024
Nov 28, 2017
May 17, 2024
May 17, 2024
Jan 24, 2020
Jul 5, 2024
Jan 9, 2020
Apr 27, 2022
Nov 28, 2017

Repository files navigation

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.

  • GitHub CI status badge
  • library update.sh status badge
    • amd64 update.sh status badge
    • arm32v5 update.sh status badge
    • arm32v6 update.sh status badge
    • arm32v7 update.sh status badge
    • arm64v8 update.sh status badge
    • i386 update.sh status badge
    • ppc64le update.sh status badge
    • s390x update.sh status badge
    • windows-amd64 update.sh status badge

Table of Contents

  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 <image name>
    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. stack.yml
  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 <image name>

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

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

content.md

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

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

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

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

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

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

metadata.json

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

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.

stack.yml

This optional file contains a small, working Compose file for Docker Swarm showing off how to use the image. To use the stack.yml, add %%STACK%% to the content.md and this will embed the YAML along with a link to directly try it in Play with Docker.

The file must work via docker stack deploy since that is how Play with Docker will launch it, but it is helpful for users to try locally if it works for docker-compose as well. 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

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

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

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/

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

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

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.