AsciiDoc3 Docker

1. The New Smart Option: AsciiDoc3 container with Docker or Podman on GNU/Linux and Windows

Tired of installing tons of software you need only in context with AsciiDoc MarkUp?
Consider about the full-featured AsciiDoc3-Container!

AsciiDoc3 provides an out-of-the-box image. You don’t need to install of your own one of the third-party-progranms like dblatex, Apache FOP, Lilypond, ePubcheck … You don’t even need a Python interpreter.
So, start the AsciiDoc3 docker experience right now! Follow the steps described below.

Windows Users: A Cause For Rejoicing

The AsciiDoc3-contaiber is extremely usefull for Windows users since Windows lacks dblatex, lxml2, source-highlight, xmllint, graphviz … And no hassle with cygwin.

asciidoc3-docker works with podman https://podman.io, too! We tested this with a fedora machine. All information given on this page about docker is valid in an analogue way. In most cases all you need to do is to replace the docker command with podman.

The AsciiDoc3 container comes in two tagged images: latest and full. See here for the differences. If you prefer the full image, replace latest with full when running through the following steps .

2. Quickstart

You want to start in a few seconds? Take a look at this quickstart. More details are given below..

2.1. Quickstart GNU/Linux

(install docker)                         

mkdir /home/$(whoami)/asciidoc3_docker   

cd /home/$(whoami)/asciidoc3_docker      

wget https://asciidoc3.org/asciidoc3_docker-3.2.2.tar.gz

tar -xzf asciidoc3_docker-3.2.2.tar.gz

docker run --name asciidoc3_docker --hostname='asciidoc3-host' --cpus='1.0' --memory 1024m --volume /home/$(whoami)/asciidoc3_docker/ad3files:/home/ad3docker/:Z --volume /home/$(whoami)/asciidoc3_docker/ad3conf:/etc/asciidoc3/:Z --user $(id -u) --network none --rm  asciidoc3/asciidoc3:latest asciidoc3 -a toc -a icons -n doc/test.txt

	→ Installing docker is beyond the scope of this text: https://docs.docker.com/get-docker/.
	→ You may choose another unique name instead of asciidoc3_docker. Avoid asciidoc3 when you plan a second full seperate installation of AsciiDoc3.
	→ $(whoami) is of course your username.
	→ This may take some time (about 30s downloading and extracting the image from https://hub.docker.com) … but only one-time at the first time! → This is a pretty long command. You may shorten this tapeworm, look here!

Yes, that’s all! It works!
Open the result with your browser:
/home/$(whoami)/asciidoc3_docker/ad3files/doc/test.html
Continue with bash-scripting and/or Next Steps.

2.2. Quickstart Windows

(install docker)

→ Installing docker is beyond the scope of this text: https://docs.docker.com/get-docker/

Open the PowerShell as a normal (non-Admin) user:

PowerShell as Normal User

PS C:\Users\<username>:  mkdir $env:UserProfile\asciidoc3_docker 
PS C:\Users\<username>:  cd  $env:UserProfile\asciidoc3_docker

You may choose another unique name instead of asciidoc3_docker. Avoid the name asciidoc3 - so you can install AsciiDoc3 with tarball/cygwin/pypi to have two independent options.

Now we have to open PowerShell as Admin since we have to download a file and add some symlinks:

PowerShell as Admin!

cd C:\Users\<username>\asciidoc3_docker 

iwr -outf asciidoc3_docker-3.2.2.tar.gz  https://asciidoc3.org/asciidoc3_docker-3.2.2.tar.gz 

tar -xzf asciidoc3_docker-3.2.2.tar.gz

	Replace <username> with your username.
	Or download here: https://asciidoc3.org/download.html → 3.7. Container (Docker, PodMan)

You’ll probably see the following nessages. That’s not a bug, it’s a feature :-)

ad3conf/images: Can't create '\\\\?\\C:\\Users\\<username>\\asciidoc3_docker\\ad3conf\\images'
ad3conf/filters/graphviz/images: Can't create '\\\\?\\C:\\Users\\<username>\\asciidoc3_docker\\ad3conf\\filters\\graphviz\\images'
ad3conf/filters/music/images: Can't create '\\\\?\\C:\\Users\\<username>\\asciidoc3_docker\\ad3conf\\filters\\music\\images'
ad3files/tests/asciidoc3api.py: Can't create '\\\\?\\C:\\Users\\<username>\\asciidoc3_docker\\ad3files\\tests\\asciidoc3api.py'
ad3files/tests/images: Can't create '\\\\?\\C:\\Users\\<username>\\asciidoc3_docker\\ad3files\\tests\\images'
ad3files/tests/data/images: Can't create '\\\\?\\C:\\Users\\<username>\\asciidoc3_docker\\ad3files\\tests\\data\\images'
ad3files/doc/images: Can't create '\\\\?\\C:\\Users\\<username>\\asciidoc3_docker\\ad3files\\doc\\images'
tar.exe: Error exit delayed from previous errors.

tar.exe doesn’t handle the symlinks …

So continue in the Admin’s PowerShell:

PowerShell as Admin!

New-Item -ItemType SymbolicLink -Name ad3conf\images -Target ad3files\images

New-Item -ItemType SymbolicLink -Name ad3conf\filters\graphviz\images -Target ad3files\images

New-Item -ItemType SymbolicLink -Name ad3conf\filters\music\images -Target ad3files\images

New-Item -ItemType SymbolicLink -Name ad3files\doc\images -Target ad3files\images

New-Item -ItemType SymbolicLink -Name ad3files\tests\images -Target ad3files\images

New-Item -ItemType SymbolicLink -Name ad3files\tests\data\images -Target ad3files\images

New-Item -ItemType SymbolicLink -Name ad3files\tests\asciidoc3api.py -Target ad3files\asciidoc3api.py

This seven commands you can execute with one line:

PowerShell as Admin!

New-Item -ItemType SymbolicLink -Name ad3conf\images -Target ad3files\images; New-Item -ItemType SymbolicLink -Name ad3conf\filters\graphviz\images -Target ad3files\images; New-Item -ItemType SymbolicLink -Name ad3conf\filters\music\images -Target ad3files\images; New-Item -ItemType SymbolicLink -Name ad3files\doc\images -Target ad3files\images; New-Item -ItemType SymbolicLink -Name ad3files\tests\images -Target ad3files\images; New-Item -ItemType SymbolicLink -Name ad3files\tests\data\images -Target ad3files\images; New-Item -ItemType SymbolicLink -Name ad3files\tests\asciidoc3api.py -Target ad3files\asciidoc3api.py

We don’t need Admin rights any more, go back to the PowerShell as a normal user and start the AsciiDoc3 container!

PowerShell as Normal User

PS C:\Users\<username>\asciidoc3_docker docker run --name asciidoc3 --hostname='asciidoc3-host' --cpus='1.0' --memory 1024m --volume C:\Users\<username>\asciidoc3_docker\ad3files:/home/ad3docker/ --volume C:\Users\<username>\asciidoc3_docker\ad3conf:/etc/asciidoc3/ --rm --network none asciidoc3/asciidoc3:latest asciidoc3 -a toc -a icons -n doc/test.txt  
...
Unable to find image 'asciidoc3/asciidoc3:latest' locally
...
Status: Downloaded newer image for asciidoc3/asciidoc3:latest
...
PS C:\Users\<username>\asciidoc3_docker

	→ Replace <username> with your username.
	→ This may take a while (downloading and extracting the image from hub.docker.com)… but only one-time at the first time! → Docker warns you that you are going to share two folders, but of course that’s just what we want. → This is a pretty long command. You may shorten this tapeworm, look here!

Yes, that’s all! It works!
Open the result with your browser:
C:\Users\<username>\asciidoc3_docker\ad3files\doc\test.html
Continue with Scripting or Next Steps.

3. Manual

3.1. Prerequisites, Installing Docker

First - you guessed it - you need Docker. Look at the in-depth installation guide at https://docs.docker.com/

GNU/Linux: user has to be member of group docker: https://docs.docker.com/engine/install/linux-postinstall/
You have to do something like sudo usermod -aG docker $USER
Windows 10/11 required: https://docs.docker.com/docker-for-windows/install/
Windows 10 Home is supported: https://docs.docker.com/docker-for-windows/install-windows-home/
A non-admin user needs permission to start a container: search the web for somthing like windows 10 docker user permission.
Check your installation by running docker version. You should see something like this (abridged)

docker version

Client:
 Version:           19.03.8 (or 20.10.2)
 API version:       1.40    (or 1.41)
 ...
Server:
 Engine:
  Version:          19.03.8 (or 20.10.2)
  API version:      1.40    (or 1.41) (minimum version 1.12)
  ...

The main thing to see here is both Client AND Server and in addition the identical version.

3.2. GNU/Linux

AsciiDoc3 needs some configuration files. To adjust them to your needs they have to be outside the container. They are mounted to the container using the option --volume. And of course you want to edit and provide your input file and the asciidoc3/a2x3-command with some options. And you would like to see the output. So we need a second --volume.

3.2.1. Directories

To keep your system clean it is highly recommended to create an own directory for asciidoc3_docker:

mkdir /home/$(whoami)/asciidoc3_docker

Or give your username explicitly

mkdir /home/<myusername>/asciidoc3_docker

3.2.2. AsciiDoc3 Docker Tarball

The next step is change into the new directory and download the AsciiDoc3 Docker tarball. The tarball provides the configuration files and other needed items. Uncompress the tarball, like so:

cd /home/<myusername>/asciidoc3_docker

wget https://asciidoc3.org/asciidoc3_docker-3.2.2.tar.gz 

tar -xzf asciidoc3_docker-3.2.2.tar.gz

Alternative way: download the tarball from https://asciidoc3.org/download → 3.7. Container (Docker, PodMan) and move it to your folder.

You’ll see two new subdirectories in asciidoc3_docker: ad3conf and ad3files. ad3conf contains the configuration files, ad3files the other files like asciidoc3api.py, the folders images, doc, and test.
If you wonder about the python files - they are given for the sake of completeness.

3.2.3. Start

Yes, that’s it. We can start:

docker run --name asciidoc3_docker --hostname='asciidoc3-host' --cpus='1.0' --memory 1024m --volume /home/$(whoami)/asciidoc3_docker/ad3files:/home/ad3docker/:Z --volume /home/$(whoami)/asciidoc3_docker/ad3conf:/etc/asciidoc3/:Z --user $(id -u) --network none --rm  asciidoc3/asciidoc3:latest asciidoc3 -a toc -a icons -n doc/test.txt

When starting the container the very first time - and only at this point - you have to wait a few seconds. The result is output here: ~/home/<username>/asciidoc3_docker/ad3files/doc/test.html

Please keep in mind: Write your own input inside the folder asciidoc3_docker - the container can’t see any file outside this folder!

3.2.4. Bash-Scripting

Of course it’s not a good idea to type docker run --name asciidoc3_docker … --rm asciidoc3/asciidoc3:latest every time you want to start the program. That’s a job for ./bashrc:

nano ~/.bashrc

Go to the end of the file and add the following line:

...
function ad3 { docker run --name asciidoc3_docker --hostname='asciidoc3-host' --cpus='1.0' --memory 1024m --volume /home/$(whoami)/asciidoc3_docker/ad3files:/home/ad3docker/:Z --volume /home/$(whoami)/asciidoc3_docker/ad3conf:/etc/asciidoc3/:Z --user $(id -u) --network none --rm  asciidoc3/asciidoc3:latest $@; }

This is one line, note the $@; } (dollar at semicolon space curly bracket) at the end.

To make this applicable

source ~/.bashrc

From now on start the container like so

ad3 asciidoc3 -a toc -a icons -n doc/test.txt

Continue with Next Steps here.

3.3. Windows

3.3.1. Installing

There’s almost nothing to add to the steps described in quickstart. So here are some hints:

AsciiDoc3 needs some configuration files. To adjust them to your needs they have to be outside the container. They are mounted to the container using the option --volume. And of course you want to edit and provide your input file and the asciidoc3/a2x3-command with some options. And you would like to see the output. So we need a second --volume.
To keep your system clean it is highly recommended to create an own directory for asciidoc3_docker: mkdir $env:UserProfile\asciidoc3_docker
You’ll see two new subdirectories in asciidoc3_docker: ad3conf and ad3files. ad3conf contains the configuration files, ad3files the other files like asciidoc3api.py, the folders images, doc, and test.
Start the container:

docker run --name asciidoc3_docker --hostname='asciidoc3-host' --cpus='1.0' --memory 1024m --volume C:\Users\<username>\asciidoc3_docker\ad3files:/home/ad3docker --volume C:\Users\<username>\asciidoc3_docker\ad3conf:/etc/asciidoc3/ --network none --rm  asciidoc3/asciidoc3:latest asciidoc3 -a toc -a icons -n doc\test.txt

Replace <username> with your username.

When starting the container the very first time - and only at this point - you have to wait a few seconds. The result is output here:
C:\Users\<username>\asciidoc3_docker\ad3files\doc\test.html

Please keep in mind: Write your own input inside the folder asciidoc3_docker - the container can’t see any file outside this folder!

3.3.2. WSL2 or Hyper-V

AsciiDoc3-Docker works both with WSL2 and Hyper-V. WSL2 seems to be more robust and is recommended by MicroSoft®. Docker also says, WSL2 provides better performance than the legacy Hyper-V backend.

3.3.3. PowerShell Function / Scripting

Of course it’s not a good idea to type docker run --name asciidoc3_docker … --rm asciidoc3/asciidoc3:latest every time you want to start the program. That’s a job for a PowerShell function:

PowerShell as Normal User

PS C:\Users\<username>\asciidoc3_docker> function ad3(){ docker run --name asciidoc3_docker --hostname='asciidoc3-host' --cpus='1.0' --memory 1024m --volume C:\Users\<username>\asciidoc3_docker\ad3files:/home/ad3docker --volume C:\Users\<username>\asciidoc3_docker\ad3conf:/etc/asciidoc3/ --network none --rm  asciidoc3/asciidoc3:latest $args }

This is one long line … replace <username> with your username.

From now on you can execute the container much easier:

PowerShell as Normal User

ad3 asciidoc3 -a toc -a icons -n doc/test.txt

The function ad3 is gone and no longer available when closing the PowerShell. To get the function loaded permanently add it to your PowerShell profile. To start with profiles you may take a look here.

Continue with Next Steps here.

3.4. MacOS

Unfortunatly we have no access to MacOS systems. The AsciiDoc3 container should run on this platform, too.

4. Next Steps

Assuming you have arranged ad3 as an alias for docker run … asciidoc3/asciidoc3:latest, here are some use cases for your new asciidoc3-container.
mytext.txt lives in directory asciidoc3_docker.

Produce a PDF

ad3 a2x3 -f pdf --fop mytext.txt

Option --fop is mandatory since image latest has no dblatex installed.

Use a source-highlighter

ad3 asciidoc3 doc/source-highlight-filter.txt

Use math formula

ad3 asciidoc3 -a asciimath -a toc -n -a icons ./doc/asciimathml.txt

You can find more exemples in folder tests/data, e.g.

ad3 asciidoc3 tests/data/newtables.txt

If you want to see how AsciiDoc3 works, you may add the -v (--verbose) option, like so

ad3 asciidoc3 -v tests/data/filters-test.txt

ad3 asciidoc3 doc/slidy-example.txt

And after that, take a look in the userguide.

5. Docker Run, Images, Dockerfile

5.1. Explore docker run … asciidoc3/asciidoc3:latest

docker run                                                                    \ # Start new container from image asciidoc3/asciidoc3
--name asciidoc3                                                              \ # Give a name to the container: optional
--hostname='asciidoc3-host'                                                   \ # Give a name to the host-container: optional
--cpus='1.0'                                                                  \ # Secureness: Limit usage of cpu: optional
--memory 1024m                                                                \ # Secureness: Limit usage of RAM: optional
--volume /home/$(whoami)/asciidoc3-docker/ad3files:/home/ad3docker/:Z         \ # Expose the needed files to the container
--volume /home/$(whoami)/asciidoc3-docker/confdir:/etc/asciidoc3/:Z           \ # Expose the needed configuration files to the container
                                                                              \ # Z is mandatory only when using SELinux
--user $(id -u)                                                               \ # Run container as current user (skip on Windows)
--rm                                                                          \ # Delete container when exit
--network none                                                                \ # Secureness: No network, container is unreachable: optional
asciidoc3/asciidoc3:latest                                                    \ # Image to use for the container

5.2. Images: latest vs. full

AsciiDoc3 provides two images = latest and full. See the table for the differences. We recommend full - latest misses some features. Tho only downside is full’s size, but you have to download it only once-in-a-lifetime …

Tabelle 1. AsciiDoc3 images: latest vs. full (the latter is pending, comes asap)
	`latest`	`full`	`remarks`
Size	`679 MB, compressed 320 MB`	`1,2 GB, compressed 480 MB`	`compressed on hub.docker.com`
asciidoc3 command	`✅`	`✅`	`-`
a2x3 command	`✅`	`✅`	`-`
a2x3 -f pdf --fop	`✅`	`✅`	`-`
a2x3 -f pdf	`❌`	`✅`	`no dblatex (consumes 350 MB) → use option --fop`
a2x3 -f pdf latexmath	`❌`	`✅`	`no dblatex again → use asciimath`
a2x3 --epubcheck	`❌`	`✅`	`no epubcheck for EPUB output`
a2x3 -f text --lynx	`❌`	`✅`	`no lynx → use default w3m`
validating docbook with jing	`❌`	`✅`	`no jing → default xmllint`
validating docbook with xmlstarlet	`❌`	`✅`	`no xmlstarlet → default xmllint`

5.3. Directory Layout

The following layout is recommended/suggested.

AsciiDoc3 Container Directory Layout

(Host - your system -, GNU/Linux or Windows)          (AsciiDoc3-container)

-/        c:\                               ||        -/.dockerenv
 |- bin     |- ...                          ||         |- bin
 |- dev     |- windows32                    ||         |- dev
 |- ...     |- ...                          ||         |- ...
 |-home     |- Users                        ||         |
     |      |                               ||         |
     - <username>                           ||         |
         |                                  ||         |
         - projects                         ||         |
           ...                              ||         |
         - private                          ||         |
           ...                              ||         |
         - asciidoc3_docker                 ||         |- etc
             |                              ||            |
             - ad3conf               <----mount---->      - asciidoc3
                 asciidoc3.conf             ||            - ...
                 help.conf                  ||            - ...
                 ...                        ||          - home
                 ...                        ||              |
             - ad3files              <----mount---->        - ad3docker
                 COPYRIGHT                  ||                 ...
                 ...                        ||
                 doc                        ||
                 tests                      ||
                 ...                        ||

5.4. Dockerfile

AsciiDoc3 Dockerfile latest

FROM ubuntu:20.04

LABEL description="asciidoc3/asciidoc3:latest"
LABEL maintainer="berthold.gehrke@gmail.com"
LABEL version="21.01.02"

# full = latest plus dblatex dvipng epubcheck jing lynx xmlstarlet

# You may ignore the following message during package install
# 'debconf: delaying package configuration, since apt-utils is not installed'

# latest 639MB
RUN apt-get update && \
    apt-get install -q -y --no-install-recommends \
            docbook-xml \
            docbook-xsl \
            docbook-xsl-ns \
            docbook5-xml \
            fop \
            graphviz \
            highlight \
            imagemagick \
            liblua5.3-0 \
            lilypond \
            python3.8 \
            python3-lxml \
            python3-pygments \
            source-highlight \
            w3m \
            xmlto && \
    apt-get clean && \
    rm -r /var/cache/apt /var/lib/apt/lists/*

RUN useradd --create-home --shell /bin/bash --no-log-init -u 1235 ad3docker && \
    echo 'ad3docker:noPassw0rd!5r' | chpasswd

WORKDIR /home/ad3docker

# 'patch' highlight, see:
# https://gitlab.com/saalen/highlight/-/issues/171
COPY ./highlight_patch /usr/bin/highlight
RUN chmod a+x /usr/bin/highlight

# install asciidoc3
ADD ./asciidoc3-3.2.2.tar.gz /home/ad3docker
RUN chmod u+x installscript && \
    ./installscript && \
    rm -rf --preserve-root /etc/asciidoc3/ && \
    chmod -R o+w /home/ad3docker && \
    chown -R ad3docker:ad3docker /home/ad3docker && \
    mkdir /etc/asciidoc3/

USER ad3docker

CMD ["/bin/bash"]

6. Security

Is the AsciiDoc3-container save?

Yes!

Container runs as a non-root-user.
Container includes no network.
Container usage of CPU and RAM is limited.
Container writes only in the user’s home-directory.
Container can not read any file outside user’s home-directory.