tvdgnr/antora repository overview

= Docker Image for Antora :uri-antora: https://antora.org⁠ :uri-asciidoctor: https://asciidoctor.org⁠ :uri-license: https://www.mozilla.org/en-US/MPL/2.0/⁠ :uri-docker: https://www.docker.com/⁠ :uri-podman: https://podman.io/⁠

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?

{uri-antora}[Antora] is a modular static site generator designed for creating documentation sites from AsciiDoc documents. Its site generator pipeline aggregates documents from versioned content repositories and processes them using {uri-asciidoctor}[Asciidoctor].

== Versioning Policy

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

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

[#use-image] == How to Use this Image

This image is published to Docker Hub. The name of the image is antora/antora. The purpose of the image is to execute the antora command inside a container (as configured by the image).

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

[#run-image] === 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 https://gitlab.com/antora/demo/demo-site[Antora⁠ demo site]. We'll provide instructions for using the {uri-docker}[Docker client] or {uri-podman}[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 http://www.projectatomic.io/blog/2015/06/using-volumes-with-docker-can-cause-problems-with-selinux/[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 [.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.

[#gitlab-ci-image] === Use the image in GitLab CI

Thanks to the custom entrypoint script ([.path]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 [.path].gitlab-ci.yml file, as shown here:

⁠[source,yaml]

⁠image: name: antora/antora

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

⁠[source,yaml]

script:

• antora antora-playbook.yml

---

[#extend-image] === Use as a Base Image

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

⁠. Create a custom Dockerfile file named [.path]Dockerfile.custom . Populate that file with the following contents: + .Dockerfile.custom [source,docker]

FROM antora/antora

⁠RUN yarn global add asciidoctor-kroki <1>

<1> Adds a custom extension to the base image.

. 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

[#build-image] == 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 (C) 2018-2020 OpenDevise Inc. and the Antora Project.

Use of this software is granted under the terms of the {uri-license}[Mozilla Public License Version 2.0] (MPL-2.0). See link:LICENSE[] to find the full license text.