Docker Image: adoc-antora

About this image

The adoc-antora image is a utility Docker image used to build the HTML contents from Asciidoc sources for www.sommerfeld.io (see sebastian-sommerfeld-io/website-sommerfeld-io on Github for more information about this website).

This image is not specific to www.sommerfeld.io and can be used to generate Antora docs from other antora playbooks. The image is not even limited to Antora and can handle Asciidoctor tasks as well.

To see which packages are shipped with this image, take a look at the Dockerfile.

How to use this image

Use with a Dockerfile

To build Antora documentation pages and run a webserver to publish these pages first create a Dockerfile. A valid Antora playbook is required for successfull Antora builds. This example expects all dependencies (the antora-playbook.yml plus the npm package.json and package-lock.json files) in the same directory as the Dockerfile.

# Stage 1: build
# Build Antora pages based on repositories from playbook. Contents are
# cloned from remote repositories because project files from local machine
# (the docker-hosts)filesystem are not present inside container.
FROM sommerfeldio/adoc-antora:latest AS build
LABEL maintainer="sebastian@sommerfeld.io"

ARG PLAYBOOK=antora-playbook.yml

RUN mkdir /antora \
    && mkdir /antora/target

COPY ${PLAYBOOK} /antora/${PLAYBOOK}
COPY package.json /antora/package.json
COPY package-lock.json /antora/package-lock.json

WORKDIR /antora

RUN antora generate ${PLAYBOOK} --stacktrace --clean --fetch

# Stage 2: run
# Run webserver with the Antora pages (built in previous stage).
FROM httpd:2.4 AS run
LABEL maintainer="sebastian@sommerfeld.io"

RUN rm /usr/local/apache2/htdocs/index.html
COPY --from=build /antora/target/docs/public /usr/local/apache2/htdocs

Then build this custom image (the Dockerfile above) and start up a Docker container to serve the html pages through the Apache httpd webserver.

DOCKER_IMAGE="local/my-antora-website:dev"
ANTORA_IMAGE="sommerfeldio/adoc-antora:latest"

docker image rm "$ANTORA_IMAGE"
docker pull "$ANTORA_IMAGE"

docker image rm "$DOCKER_IMAGE"
docker build --no-cache -t "$DOCKER_IMAGE" .

docker run --rm -p 8000:80 "$DOCKER_IMAGE"

Use without a Dockerfile

To use the image without a Dockerfile run the following command. This create a /tmp/antora directory which contains all generated HTML, CSS, JS, etc.

  docker run -it --rm \
    --volume "$(pwd):$(pwd)" \
    --volume "/tmp/antora:/tmp/antora" \
    --workdir "$(pwd)" \
    sommerfeldio/adoc-antora:latest antora generate antora-playbook.yml --stacktrace --clean --fetch

Risks and Technical Debts

Scale for Probability and Impact: Low, Medium and High

# Title Description Probability Impact Response

1

-

-

-

-

-

Contact

Feel free to contact me via sebastian@sommerfeld.io or visit my website https://www.sommerfeld.io.