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/.
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:
To see the full list of packages/software included, check out the setup script used by the container: this script.
All you need is install Docker as shown below.
macOS:
Windows:
Linux:
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
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 asiso-12345.adoc
-
{flavor}
is the flavor of Metanorma document, such asiso
-
{extensions}
is a list of extensions desired, such asxml,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’sWORKDIR
-
the
metanorma
command is set in the container’sENTRYPOINT
The full command is actually this:
docker run -v "$(pwd)":/metanorma/ -w /metanorma metanorma/metanorma metanorma compile -t iso -x {extensions} {my-document-file}
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.
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
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
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 inIMAGE_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
The Makefile
supports the following commands for building:
make {build,push,tag,clean-remote,clean-local}-{container-flavor}
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
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
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
The image is available open source under the terms of the MIT License.