Run Antora in a Container

The Antora project provides a Docker image that you can use to run the antora command inside a container (a process known as containerization). The benefit of this approach is that you can bypass installing Antora and get right down to running it. All you need is Docker or Podman.

Assumptions:

  • You have Docker (command: docker) or Podman (command: podman) installed on your machine.

  • The Docker daemon is running on your machine (not required when using Podman).

  • You have configured your own playbook or you’re using the Demo playbook.

On this page, you’ll learn:

  • How to run Antora inside a container using the official Docker image for Antora.

  • How to give the container access to a local directory.

  • How to extend the Docker image for Antora to create your own image.

Docker image for Antora

Docker is a tool for running container images (officially OCI images). You can think of a container image as an application in a box. Inside that box is everything you need to run the application, including the code, the runtime, the settings, and even the operating system itself. Containers not only isolate software from the host environment, they also make it easy to get up and running quickly. And that’s a perfect way to discover and explore Antora!

The Antora project provides an official Docker (OCI) image named antora/antora for running Antora inside a container. This image is published to the antora/antora project on Docker Hub.

This image is a drop-in replacement for the antora command. Rather than installing the antora command on your own computer or in a CI environment, you simply run the command by running the container. In fact, the CI job for the Antora documentation site uses this image to generate the documentation you’re currently reading.

Let’s find out how to run it.

Run the Antora image

To demonstrate how to use this image, we’ll be using the Antora demo site. Start by cloning the playbook repository for the demo site, then switch to the newly created folder:

~ $ git clone https://gitlab.com/antora/demo/docs-site.git && cd "$(basename $_ .git)"

Next, execute the docker run command to invoke the entrypoint command (i.e., antora) for this image using the Docker client:

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

This command spins up a new container from the image, mounts the current directory as the path /antora inside the container, runs the antora command (as the current user), then stops and removes the container. It’s exactly like running a locally installed antora command, only you’re using container superpowers to do it!

Fix the permission denied error when accessing /.cache

If your local uid (i.e., $(id -u)) is not 1000, you may encounter the following error when running Antora in the container:

error: EACCES: permission denied, mkdir '/.cache'

This happens because the default cache directory is resolved relative to the user’s home directory and the home directory of an unmapped user is /. That’s why you see the path /.cache in the message, which is not a writable location.

The solution to this problem is to modify the location of the cache directory.

Alternately, you can execute the podman run command to invoke the entrypoint command for this image using Podman:

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

The advantage of Podman is that it’s more secure. It runs in user space and does not rely on a daemon. To continue using Podman, replace docker with podman (and drop the -u option) in any of the commands below.

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 host system.

Option flags

Here are explanations for some of the option flags used in the run command:

-t

This flag allocates a pseudo-TTY, which is required if you want to see progress bars for git operations. If you don’t need to see these progress bars, you can omit this flag.

-u $(id -u)

This option tells Docker to run the entrypoint command (i.e., antora) as the current user. If you use the :Z modifier on the volume mount without specifying this option, the generated files are (most likely) written as the root user (and thus become rather tricky to delete). This option is not required when using Podman.

-v

A volume mount that maps the current directory on your local system (represented by $PWD) to the /antora directory inside the container. This allows files written by the container to be visible on your local system, which is the whole point of using the container.

:Z (on the volume mount)

This flag is only required if you’re running a Linux distribution that has SELinux enabled, such as Fedora. This option allows you to use volume mounts when running SELinux.

-w

This option tells Docker to switch to the specified directory (i.e., $PWD) before invoking the entrypoint command. You will use this option if you want to run the antora command from a directory other than /antora inside the container.

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.

Cache directory location

If Antora cannot write the default cache directory, or you simply want the cache directory to be located inside the mounted directory, specify a playbook-relative directory using the --cache-dir option:

docs-site $ docker run -u $(id -u) -v $PWD:/antora:Z --rm -t antora/antora --cache-dir=./.cache/antora antora-playbook.yml

An alternate approach is to override the HOME directory of the container user:

docs-site $ docker run -u $(id -u) -e HOME=/antora -v $PWD:/antora:Z --rm -t antora/antora antora-playbook.yml

In both cases, all files either cached or generated by Antora are neatly contained inside the mounted directory and owned by the current user. This configuration also has the benefit that the cache will be preserved between runs, so it’s a good idea to use regardless.

Enter the container

If you want to shell into the container instead of having it run the antora command, append the name of the shell (ash) to the container run command:

docs-site $ docker run -u $(id -u) -v $PWD:/antora:Z --rm -it antora/antora ash

Now you can run the antora command from anywhere inside the running container. This mode is useful to use while editing. Since the container continues to run, you can quickly execute the antora command.

If the base Antora image doesn’t include everything you need for your site, you can extend it.

Extend the Antora image

You can use this image as a base for your own Docker image. The image comes preconfigured with Yarn so you can install additional extension libraries, such as Asciidoctor Kroki (asciidoctor-kroki) for adding diagram support to AsciiDoc.

  1. Clone the docker-antora repository and switch to it:

    ~ $ git clone https://gitlab.com/antora/docker-antora.git && cd "$(basename $_ .git)"

  2. Create a custom Dockerfile file named Dockerfile.custom.

  3. Populate the file with the following contents:

    Example 1. Dockerfile.custom
    FROM antora/antora

RUN yarn global add asciidoctor-kroki (1)
    1 Adds a custom extension to the base image.

  4. Build the image using the following command:

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

Once the build is finished, you’ll have a new image available on your machine named local/antora:custom. To see a list of all your images, run the following command:

$ docker images

To run this image, switch back to your playbook project and run the container as follows:

docs-site $ docker run -u $(id -u) -v $PWD:/antora:Z --rm -t local/antora:custom antora-playbook.yml

If you want to share this image with others, you’ll need to publish it. Consult the Docker documentation to find out how.