Metanorma Docker Container (based on Ubuntu Linux)

Docker Hub: metanorma/metanorma

Purpose

The Metanorma Docker container provides all dependencies necessary for its usage.

This is the cross-platform solution for Metanorma that across operating systems where supported by Docker (including Windows).

If you want Metanorma to affect your local machine’s environment as little as possible, using Docker may be the best choice — although not without some performance tradeoff.

For those who need better performance, or wish to avoid a Docker setup (e.g. administrative rights, memory usage), please refer to alternative Metanorma installation methods at https://metanorma.com/author/topics/install/.

What’s included?

Under the hood, the Metanorma toolchain depends on couple of software/packages.

To ease installation, the Docker image is already fully setup so you don’t have to worry about anything.

At a high level, the image includes the following:

• PlantUML with the Java subsystem

• Ruby

• Inkscape

• Metanorma and Metanorma CLI

To see the full list of packages/software included, check out the setup script used by the container: this script.

Usage

Prerequisites

All you need is install Docker as shown below.

macOS:

• Docker Desktop for Mac

Windows:

• Docker Desktop for Windows (Windows 10)

• Docker Toolbox for legacy Windows

Linux:

• Docker CE for Ubuntu

• Docker CE for CentOS

• Docker CE for Debian

Pulling the container

This container is published at the Docker Registry as docker.io/metanorma/metanorma or metanorma/metanorma, and can be pulled with the following command:

docker pull metanorma/metanorma

Compiling a Metamorma document via docker

In a directory containing the Metanorma document, run this:

docker run -v "$(pwd)":/metanorma/ metanorma/metanorma metanorma compile -t {flavor} -x {extensions} {my-document-file}

Where,

• {my-document-file} is the name of the Metanorma document file, such as iso-12345.adoc

• {flavor} is the flavor of Metanorma document, such as iso

• {extensions} is a list of extensions desired, such as xml,html,doc

Example (real-life):

docker run -v "$(pwd)":/metanorma metanorma/metanorma metanorma -t iso -x xml,html,doc,pdf iso-8601-2-en.adoc

The above command actually uses a couple assumptions set in the built container itself, including:

• the /metanorma path is set within the container’s WORKDIR

• the metanorma command is set in the container’s ENTRYPOINT

The full command is actually this:

docker run -v "$(pwd)":/metanorma/ -w /metanorma metanorma/metanorma metanorma compile -t iso -x {extensions} {my-document-file}

Updating your document to support Docker compilation

The :local-cache-only: document attribute should be set in your document in order to take advantage of local caching of bibliographic items fetched from the Internet.

Note	Normally, the Metanorma toolchain assumes that you have a global bibliographic cache located in ~/.relaton/cache and ~/.iev/cache. However, when run in a docker container, the global cache is not shared between the host and the container.

By setting :local-cache-only:, Metanorma will not generate a global bibliographic cache, and will store a cache instance for each document in the local working directory, which is shared between the host and the container, as in:

• ./relaton/cache; and

• ./iev/cache.

The document attribute is to be set in the document header, like this:

= ISO 8601-2
:docnumber: 8601
:partnumber: 2
:copyright-year: 2019
:title-intro-en: Date and time
:title-main-en: Representations for information interchange
:title-part-en: Extensions
// ...
:local-cache-only:

These files can also be checked-in into version control.

Development guide

Container flavors

There are two supported container flavors:

• metanorma: official release of the Metanorma container, using released gems

• mn: experimental release of the Metanorma container, using unreleased (but hopefully functional) gems

Running the Metamorma container via the Makefile

The Makefile makes developing the container much simpler.

To start the metanorma container and enter it with bash, all you need is:

make run-metanorma

To kill the container:

make kill-metanorma

The Makefile supports the following commands related to running:

make {run,kill,rm,rmf}-metanorma

Prerequisites

This Makefile allows you to build the Metanorma container yourself.

All you have to set is a couple environment variables.

For example, if you use AWS' ECR, you can set this:

export NS_REMOTE=${account-id}.dkr.ecr.${region}.amazonaws.com/${account-name}
export DOCKER_LOGIN_CMD='aws ecr get-login --no-include-email \
  --region=${region} --registry-ids=${ecr-registry-id}'

If you want to build other containers you can add these:

export ITEMS="1 2"
export IMAGE_TYPES="metanorma metanorma-ubuntu-21.10"
export VERSIONS="1.0 1.0"
export ROOT_IMAGES="ubuntu:20.04 ubuntu:21.10"

The environment variables are used for:

NS_REMOTE

the namespace for your remote repository (to separate from builds intended for local consumption)

DOCKER_LOGIN_CMD

how you authenticate against your repository

ITEMS

a sequential number list for iterating IMAGE_TYPES, its numbers are indexes to the content in IMAGE_TYPES

IMAGE_TYPES

the different containers you support. Remember to create a directory for each of these names with a Dockerfile.in within. See existing examples.

VERSIONS

how you want to tag the resulting images, for now we use the same version across all images which defined in VERSION.mak

ROOT_IMAGES

the container your new image should be based on

Makefile build targets

The Makefile supports the following commands for building:

make {build,push,tag,clean-remote,clean-local}-{container-flavor}

Updating container flavors

All files relating to building a certain container flavor is located in the {container-flavor} directory.

For the metanorma and mn flavors, we update using this procedure:

pushd metanorma
bundle update
popd
# Gemfile.lock is updated

Then, we build and push the container:

make btp-metanorma

Lastly, we tag and push the built container as latest.

make latest-tp-metanorma

Chain commands

If you feel tired typing out this:

make build-metanorma tag-metanorma push-metanorma

We have a list of shortcut targets to save you from repeating fingers. For example:

# equivalent to make {build,push}-{container-flavor} latest-{tag,push}-{container-flavor}
make btp-metanorma latest-tp-metanorma

The shortcut targets are:

btp-{target}

build + tag + push

bt-{target}

build + tag

tp-{target}

tag + push

Push the container by CI

Currently CI do docker push only for tags on master. So to trigger build you need to create tag on master and push it, example:

git tag v1.2.3
git push origin master --tags

Important requirement for tag: it must correlate with versioning of metanorma-cli.

Tags allow you to fast switch between different versions List of tags can be obtained with:

git tag --list

License

The image is available open source under the terms of the MIT License.