Docker Image for Antora

This repository hosts the official Docker image for Antora. The Docker image is used to run Antora inside a container using the Docker client or Podman (or any client that adheres to the OCI standard).

What is Antora?

Antora is a modular static site generator designed for creating documentation sites from AsciiDoc documents. Antora’s site generator aggregates documents from versioned content repositories, processes them using Asciidoctor, and publishes them together as a documentation site.

Versioning Policy

There’s exactly one version of the image for each released version of Antora. That relationship includes Antora prereleases (e.g., 2.3.0-beta.1).

The greatest stable release is published under the Docker tag "latest". The greatest prerelease is published under the Docker tag "testing". These tags correspond to the tags applied to the packages in the npm repository.

How to Use this Image

The name of the image is antora/antora. This image is published to Docker Hub. The purpose of the image is to execute the antora command inside a container (as configured by the image). Currently, this image only provides a linux/amd64 container.

If you want to help improve this image, you should learn how to build and install it locally.

Run the Image Directly

This image is primarily designed to be used as a command in a box. You can use this image as a replacement for the antora command to execute a playbook. (The arguments that follow the name of the image are assumed to either be arguments to the antora command or a local command). The benefit of using this image is that you don’t have to install Antora itself.

To demonstrate how to use this image, we’ll be using the Antora demo site. We’ll provide instructions for using the Docker client or Podman.

Start by cloning the playbook repository for the demo site, then switch to the newly created folder:

$ git clone https://gitlab.com/antora/demo/demo-site.git
  cd demo-site

Next, execute the docker run command to start a container process from this image, which implicitly runs the antora command inside the container:

$ docker run -v $PWD:/antora --rm -t antora/antora --stacktrace antora-playbook.yml

The -t flag allocates a pseudo-TTY, which is required if you want to see the progress bars for git operations.

Alternately, you can execute the podman run command:

$ podman run -v $PWD:/antora --rm -t antora/antora --stacktrace antora-playbook.yml

The advantage of Podman is that it is more secure. It runs in user space and does not rely on a daemon.

If you’re running a Linux distribution that has SELinux enabled, like Fedora, you’ll need to add the :Z (or :z) modifier to the volume mount. You’ll also want to add the -u $(id -u) option to instruct Docker to run the entrypoint command as the current user. Otherwise, files will be written as root and thus hard to delete. Here’s the command you’ll use:

$ docker run -u $(id -u) -v $PWD:/antora:Z --rm -t antora/antora --stacktrace antora-playbook.yml

When using Podman, the -u flag is not required since the container is already run in user space.

$ podman run -v $PWD:/antora:Z --rm -t antora/antora --stacktrace antora-playbook.yml

Although tempting, the --privileged flag is not needed. To learn more about using volume mounts with SELinux, see the blog post Using Volumes with Docker can Cause Problems with SELinux.

Warning

If your uid is not 1000, you may encounter the following error: error: EACCES: permission denied, mkdir '/.cache' This happens because the default cache dir resolves relative to the user’s home directory and the home directory of the Docker user is / (hence the path /.cache). You can fix this problem by setting the cache dir relative to the playbook when running Antora: $ docker run -u $(id -u) -v $PWD:/antora:Z --rm -t \ antora/antora --cache-dir=./.cache --stacktrace antora-playbook.yml

If you want to shell into the container, use the following command:

$ docker run -v $PWD:/antora:Z --rm -it antora/antora sh

This command allows you to run the antora command from a prompt inside the running container, but will still generate files to the local filesystem. The reason this works is because, if the first argument following the image name is a local command, the container will execute the specified command instead of antora.

Align with local paths

If you use the volume mapping $PWD:/antora:Z, you may notice that local paths reported by Antora don’t map back to your system. That’s because, as far as Antora is concerned, /antora is the current working directory. To remedy this problem, you need to map your current working directory into the container, then switch to it before running Antora. To do so, use this volume mount instead:

-v $PWD:$PWD:Z -w $PWD

Notice the addition of the -w option. This option tells Antora to switch from /antora to the directory you have mapped. Now, when Antora reports local paths, they will match paths on your system.

Use the git client

Although this image does not include git, it does provide access to the CLI for the git client used by Antora (isomorphic-git). The name of this CLI is isogit. You can use it to clone a repository as follows:

$ mkdir /tmp/docs-site
  cd /tmp/docs-site
  isogit clone --url=https://gitlab.com/antora/docs.antora.org.git

You can trim that clone down to a single commit by adding additional flags:

isogit clone --url=https://gitlab.com/antora/docs.antora.org.git --singleBranch --noTags --depth=1

Note that the isogit clone command does not create a directory for the repository clone like the git clone command. Therefore, you have to create the repository first, switch to it, then run the clone command.

Use the image in GitLab CI

Thanks to the custom entrypoint script (docker-entrypoint.sh), this image will work on GitLab CI without having to specify the entrypoint. Simply reference the image name at the top of the .gitlab-ci.yml file, as shown here:

image:
  name: antora/antora

By using this image, you can invoke the antora command from a script clause in .gitlab-ci.yml as follows:

  script:
  - antora antora-playbook.yml

Use as a Base Image

You can use this image as a base to create your own image.

1. Create a custom Dockerfile file named Dockerfile.custom

2. Populate that file with the following contents:

   Dockerfile.custom

   FROM antora/antora
   
   RUN yarn global add asciidoctor-kroki (1)

   1. Adds a custom extension to the base image.

3. Build the image using the following command:

   $ docker build --pull -t local/antora:custom -f Dockerfile.custom .

Once the build is finished, you can use the image name local/antora:custom to run the container.

$ docker run --rm -t local/antora:custom version

To see a list of your images, run the following command:

$ docker images

How to Build this Image

To build this image locally, use the following command:

$ docker build --pull -t local/antora .

The build make take awhile to complete. Once it’s finished, you can use the image name local/antora (i.e., local/antora:latest) to run the container.

Copyright and License

Copyright © 2018-present OpenDevise Inc. and the Antora Project.

Use of this software is granted under the terms of the Mozilla Public License Version 2.0 (MPL-2.0). See LICENSE to find the full license text.