// The lines beginning with // hard against the left margin are ignored by asciidoc3.py!
// This file 'docker.txt' is based on the page 'https://asciidoc3.org/en/docs/documentation/docker'
// To see 'data-uri' working, try 'asciidoc3 -v -a icons -a data-uri doc/docker.txt': all images, admonitions, and callouts are base64-embedded!
// To see the icons in the produced PDF, try 'a2x3 -f pdf -v --icons doc/docker.txt' or 'a2x3 -f pdf --fop -v --icons doc/docker.txt'
// You may use the 'easier' way to produce a PDF:
// asciidoc3 --pdf=fop -v doc/docker.txt
// To see the icons in PDF the next line is helpful
// a2x3: --icons




== Container

=== Docker / Podman

[TIP]
This is a smart option: AsciiDoc3 container with https://docker.com[Docker] or https://podman.io[Podman] on GNU/Linux or Windows or MacOS

You don't need to install one of the third-party-programs like dblatex, Apache FOP, Lilypond, ePubcheck ... You don't even need a Python interpreter. +
The AsciiDoc3-container is extremely usefull for Windows users since Windows lacks dblatex, lxml2, source-highlight, xmllint, graphviz ... And no hassle with cygwin. +
GNU/Linux users may benefit from Docker, too: all third-party programs wait in the wings.

AsciiDoc3 provides two out-of-the-box images on https://hub.docker.com/u/asciidoc3[Docker Hub]: 'latest' (= default = 'full') and 'small'. Learn <<Manual,more>>.  
See <<TheImages,here>> for the differences. If you prefer the small image, replace latest with small when running through the following steps. +
Let's start the AsciiDoc3 docker experience right now! Follow the steps described below.




== Quickstart [[quickstartsection]]
You want to start in a few seconds? Take a look at this quickstart. More details are given <<Manual,below>>. +
The next section is for GNU/Linux users - Windows starts <<Dockerwindows,here>>.

=== Quickstart GNU/Linux



-------------------------------------
(install docker)                         <1> <2>

mkdir /home/$(whoami)/asciidoc3_docker   <3> <4>

cd /home/$(whoami)/asciidoc3_docker

wget https://asciidoc3.org/docs/download/asciidoc3-latest.tar.gz <5>

tar -xzf asciidoc3-latest.tar.gz -C ~/asciidoc3_docker 

rm asciidoc3-latest.gz

docker run --name asciidoc3_docker --hostname='asciidoc3_host' \
--cpus='1.0' --memory 1024m \
--volume /home/$(whoami)/asciidoc3_docker/:/home/ad3docker/:Z \
--user $(id -u) --rm asciidoc3/asciidoc3:latest \
./asciidoc3.py -a toc -a icons -n doc/test.txt  <6>

-------------------------------------

 
<1> https://docs.docker.com/get-docker/[Installing docker] is beyond the scope of this site.

<2> Don't forget 'sudo usermod -aG docker $USER' and logout/login. 

<3> You may choose another unique name instead of 'asciidoc3_docker'.

<4> $(whoami) is of course your username.

<5>  &#9989; Yes! The tarball works also with Docker.

<6> This is an oneliner. Be careful to provide the correct path and directories.


Allow about 12s for downloading and extracting the image ... but only one-time at the first time! +
This is a pretty long command. You may <<Alias,shorten>> this tapeworm.


=== Podman

asciidoc3_docker works with https://podman.io[podman], 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'.


[IMPORTANT]
*Yes, that's all! It works!* +
Open the result with your browser: +
/home/$(whoami)/asciidoc3_docker/doc/test.html +
Continue with <<Alias,bash-scripting>> or <<NextSteps,Next Steps>>.

[[Dockerwindows]]
=== Quickstart Windows 

-------------------------------------
(install docker) <1>
-------------------------------------

<1> https://docs.docker.com/desktop/setup/install/windows-install/[Installing docker] is beyond the scope of this site.


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

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

<1> You may choose another unique directory instead of 'asciidoc3_docker'. 

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

----------------------
cd C:\Users\<username>\asciidoc3_docker <1>
(the next line with admin rights)
iwr -outf AsciiDoc3-402-setup.exe https://asciidoc3.org/docs/download/AsciiDoc3-402-setup.exe <2> <3>
----------------------

<1> Replace <username> with your username.

<2> Or download here: link:../../download[Download Container (Docker/Podman)]
<3>  &#9989; Yes! The setup.exe works also with Docker.

Install the exe in the usual way into folder asciidoc3_docker.


///////////
Windows11 generates the symlinks with the built-in archive tool (admin rights). Windows10 needs a tool like 7-zip (admin rights).
//////////

If the symlinks are not present after this step, you may add them manually. +
Strictly speaking symlinks are not mandatory. You may add/copy the images/icons manually to the appropriate location (the folder 'images'). 

.Add symlinks to images/icons manually
----------------------------
(admin rights)
(remove items if they exists before adding the symlink)

Remove-Item asciidoc3.conf, if it exists
New-Item -ItemType SymbolicLink -Name asciidoc3.conf -Target conf\asciidoc3.conf

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

Remove-Item conf\backends\text.conf
New-Item -ItemType SymbolicLink -Name conf\text.conf -Target conf\backends\text.conf

Remove-Item filters\music\images
New-Item -ItemType SymbolicLink -Name images -Target filters\music\images

Remove-Item filters\graphviz\images
New-Item -ItemType SymbolicLink -Name images -Target filters\graphviz\images

Remove-Item filters\music\images
New-Item -ItemType SymbolicLink -Name images -Target filters\music\images

------------------------------


You can execute this with one line:

(admin rights)

---------------
Remove-Item asciidoc3.conf; New-Item -ItemType SymbolicLink -Name asciidoc3.conf -Target conf\asciidoc3.conf; Remove-Item doc\images; New-Item -ItemType SymbolicLink -Name images -Target doc\images; Remove-Item conf\backends\text.conf; New-Item -ItemType SymbolicLink -Name conf\text.conf -Target conf\backends\text.conf; Remove-Item filters\music\images; New-Item -ItemType SymbolicLink -Name images -Target filters\music\images; Remove-Item filters\graphviz\images; New-Item -ItemType SymbolicLink -Name images -Target filters\graphviz\images; Remove-Item filters\music\images; New-Item -ItemType SymbolicLink -Name images -Target filters\music\images

---------------



We don't need Admin rights to start a container, if you configured docker in this way: https://www.geeksforgeeks.org/add-myself-to-the-docker-users-group-on-windows/[Docker without admin rights]. +
But you may of course start the container as admin, there is no risk here.

PowerShell as normal User
------------------------------------
PS C:\Users\<username>\asciidoc3_docker docker run --volume C:\Users\<username>\asciidoc3_docker\:/home/ad3docker/ --rm --network none asciidoc3/asciidoc3:latest ./asciidoc3.py -a toc -a icons -n doc/test.txt <1>
...
Unable to find image 'asciidoc3/asciidoc3:latest' locally
...
Status: Downloaded newer image for asciidoc3/asciidoc3:latest <2>
...
PS C:\Users\<username>\asciidoc3_docker
-------------------------------------

<1> Replace <username> with your username.
<2> This may take a while (15s) ...

(... downloading and extracting the image from hub.docker.com) ... but only one-time at the first time! This is a pretty long command. You may shorten this tapeworm, look <<winscripting,here>>!


[IMPORTANT]
*Yes, that's all! It works!* +
Open the result with your browser: +
C:\Users\<username>\asciidoc3_docker\doc\test.html +
Continue with <<winscripting,Scripting>> or <<NextSteps,Next Steps>>.


[[Manual]]
== Manual
=== Prerequisites, Installing Docker

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

- GNU/Linux: user has to be member of https://docs.docker.com/engine/install/linux-postinstall/[group 'docker']. +
  You have to do something like 'sudo usermod -aG docker $USER'

- Docker runs on https://docs.docker.com/docker-for-windows/install/[Windows 10/11]. +
  A non-admin user needs permission to start a container: search the web for somthing like 'windows 11 docker user permission'. +
  Docker seems to be well integrated in the Windows ecosystem in the meantime. 
  
- Check your installation by running 'docker version' or start your docker experience with 'docker run hello-world'.


=== GNU/Linux

AsciiDoc3 needs some configuration files. To adjust them to your needs they have to be 'outside' the container. 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, don't you? +
These things are mounted to the container using the option '--volume'. 


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

------------------
mkdir /home/$(whoami)/asciidoc3_docker
------------------



==== AsciiDoc3 Docker Tarball

See above <<quickstartsection,quickstart>>.

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

[[Alias]]
==== 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/:/home/ad3docker/:Z --user $(id -u) --network none --rm  asciidoc3/asciidoc3:latest $@; }   <1>

-----------------

<1> 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 <<NextSteps,Next Steps>>.


=== Windows

==== 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'.

- To keep your system clean it is highly recommended to create an own directory for asciidoc3_docker: 'mkdir $env:UserProfile\asciidoc3_docker'

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


[[winscripting]]
==== 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 --network none --rm  asciidoc3/asciidoc3:latest $args } <1>
-----------------------
<1> One long line. Replace <username> with your username.

From now on you can execute the container much easier:

--------------
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 https://www.howtogeek.com/126469/how-to-create-a-powershell-profile/[here].

Continue with <<NextSteps,Next Steps>>.


=== MacOS

The AsciiDoc3 container should run on this platform, too.


[[NextSteps]]
== 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 <1>
-------------

<1> Option --fop is mandatory when using image 'small': there is 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 link:../userguide[userguide]. 


== Docker Run, Images, Dockerfile

=== 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/:/home/ad3docker/: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
------------------------


[[TheImages]]

=== Images: latest vs. small

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

[NOTE]
To run 'small' just replace 'docker run ... asciidoc3/asciidoc3:latest' with 'docker run ... asciidoc3/asciidoc3:small'

.AsciiDoc3 images: latest vs. full
// edited to avoid an xmllint-error:
//[width="97%",cols=">s,^m,^m,^m",frame="topbot"]
[width="97%",frame="topbot"]
|==========================
|        | *small*  | *latest* | remarks
|Size | 679 MB, compressed 320 MB | 1,2 GB, compressed 480 MB | compressed on hub.docker.com
//|asciidoc3 command     | &#9989; | &#9989; | -
//|a2x3 command  | &#9989;   | &#9989; | -
//|a2x3 -f pdf --fop (or asciidoc3 --pdf=fop) | &#9989;  | &#9989; | -
//|a2x3 -f pdf   | &#10060;  | &#9989; | no dblatex (consumes 350 MB) -> use option --fop
//|a2x3 -f pdf 'latexmath' | &#10060;  | &#9989; | no dblatex again -> use asciimath
//|a2x3  --epubcheck  | &#10060;   | &#9989; | no epubcheck for EPUB output
//|a2x3 -f text --lynx   | &#10060;  | &#9989; | no lynx -> use default w3m
//|validating docbook with jing | &#10060; | &#9989; | no jing -> default xmllint
//|validating docbook with xmlstarlet | &#10060; | &#9989; | no xmlstarlet -> default xmllint
|==========================


=== Directory Layout

The following layout is recommended. If you install as suggested, this is what you'll see.  

.AsciiDoc3 Container Directory Layout
--------------------
(Host - GNU/Linux or Windows)          (AsciiDoc3-container)

-/        c:\                    ||        -/.dockerenv
 |- bin     |- ...               ||         |- bin
 |- dev     |- windows32         ||         |- dev
 |- ...     |- ...               ||         |- ... 
 |-home     |- Users             ||         |
     |      |                    ||         |
     - <username>                ||         |
         |                       ||         |
         - projects              ||         |  
           ...                   ||         |
         - private               ||         |
           ...                   ||         |
           ...                   ||         |- home 
           ...                   ||         |  |
         - asciidoc3_docker  <----mount---->   - ad3docker
             |                   ||              ...
             - asciidoc3.conf    ||              ... 
             - COPYRIGHT         ||              ...
             - asciidoc3.py      ||              ...
             - a2x3.py           ||              ...
                 ...             ||
                 doc             ||
                 filters         ||
                 conf            ||

--------------------



=== Dockerfile

AsciiDoc3 Dockerfile latest / full

-------------------------
FROM debian:trixie-slim

LABEL description="asciidoc3/asciidoc3:latest"
LABEL version="4.1.0"
LABEL release-date="2026-10-10"
LABEL maintainer="berthold.gehrke@gmail.com"

# small = latest minus dblatex dvipng epubcheck jing lynx xmlstarlet

RUN apt-get update && \
    apt-get install -q -y --no-install-recommends \
            vim \
            dblatex \
            docbook-xml \
            docbook-xsl \
            docbook-xsl-ns \
            docbook5-xml \
            dvipng \
            epubcheck \
            fop \
            graphviz \
            highlight \
            imagemagick \
            jing \
            liblua5.4-0 \
            lilypond \
            lynx \
            python3 \
            python3-lxml \
            python3-pygments \
            source-highlight \
            w3m \
            xmlstarlet \
            python-is-python3 \
            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

# install asciidoc3
ADD asciidoc3dockerpodmanimage.tar.gz /home/ad3docker                       <1> 
RUN cp -r /home/ad3docker/AsciiDoc3_docker_files/. /home/ad3docker && \
    rm -r /home/ad3docker/AsciiDoc3_docker_files && \
    rm -r /home/ad3docker/misc && \
    cp -r /home/ad3docker/src/. /home/ad3docker && \
    rm -r /home/ad3docker/src/ && \
RUN chmod -R o+w /home/ad3docker && \
    chown -R ad3docker:ad3docker /home/ad3docker && \
    ln --symbolic /usr/bin/python3 /usr/bin/pycont                       <2>

USER ad3docker
CMD ["/bin/bash"]
------------------------


<1> The ad3docker folder may be empty!

<2> This is for debugging ...


[TIP]
You are invited to create your own AsciiDoc3-image if you need your individual layout. 

To do so, you may need the tarball we've used, see in section link:../../download['download'].

== 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. 


