= Metanorma Docker Container (based on Ubuntu Linux)
image:https://github.com/metanorma/metanorma-docker/workflows/build-push/badge.svg["Build Status", link="https://github.com/metanorma/metanorma-docker/actions?workflow=build-push"] image:https://img.shields.io/github/issues-pr-raw/metanorma/metanorma-docker.svg["Pull Requests", link="https://github.com/metanorma/metanorma-docker/pulls"] image:https://img.shields.io/github/commits-since/metanorma/metanorma-docker/latest.svg["Commits since latest",link="https://github.com/metanorma/metanorma-docker/releases"]
image:https://badgen.net/docker/size/metanorma/metanorma/alpine-latest?icon=docker&label=alpine["metanorma:alpine-latest", link="https://hub.docker.com/r/metanorma/metanorma/tags?name=alpine"] image:https://badgen.net/docker/size/metanorma/metanorma/ubuntu-latest?icon=docker&label=ubuntu["metanorma:ubuntu-latest", link="https://hub.docker.com/r/metanorma/metanorma/tags?name=ubuntu"] image:https://badgen.net/docker/size/metanorma/metanorma/ruby-latest?icon=docker&label=ruby["metanorma:ruby-latest", link="https://hub.docker.com/r/metanorma/metanorma/tags?name=ruby"]
https://hub.docker.com/r/metanorma/metanorma/tags[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:
To see the full list of packages/software included, check out the setup script used by the container: https://github.com/metanorma/metanorma-linux-setup/blob/master/ubuntu.sh[this script].
== Usage
=== Prerequisites
All you need is install Docker as shown below.
macOS:
Windows:
Linux:
=== Pulling the container
This container is published at the
https://hub.docker.com/r/metanorma/metanorma/[Docker Registry] as
docker.io/metanorma/metanorma or metanorma/metanorma,
and can be pulled with the following command:
=== Compiling a Metamorma document via docker
In a directory containing the Metanorma document, run this:
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,docExample (real-life):
The above command actually uses a couple assumptions set in the built container itself, including:
/metanorma path is set within the container's WORKDIRmetanorma command is set in the container's ENTRYPOINTThe full command is actually this:
=== 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:
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 gemsmn: 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:
To kill the container:
The Makefile supports the following commands related to running:
=== 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:
If you want to build other containers you can add these:
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:
=== 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
Then, we build and push the container:
Lastly, we tag and push the built container as latest.
=== Chain commands
If you feel tired typing out this:
We have a list of shortcut targets to save you from repeating fingers. For example:
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:
Important requirement for tag: it must correlate with versioning of https://github.com/metanorma/metanorma-cli/releases[metanorma-cli].
Tags allow you to fast switch between different versions List of tags can be obtained with:
== License
The image is available open source under the terms of the http://opensource.org/licenses/MIT[MIT License].