Install docToolchain

Ralf D. Müller Jakob Genßler Michael Rossner igoreq1010 Markus Napp Markus Napp RFUCN Simon rmi2hi Timo Abele Ralf D. Müller Kevin Latka Max Hofer Pascal Euhus Frank Joseph Jochen Kraushaar Miranda Boerlage Nicca3006 Jeremie Bresson Bennykillua Jérémie Bresson T8xi Michael Krauße Ralf D. Müller stehlih Dr. Stefan Pfeiffer Alexander Schwartz feinstaub Jakub J Jablonski jakubjab Jorge Dr. Gernot Starke Lars Francke

11 minutes to read

Installation Overview

docToolchain is composed of two parts:

  • doctoolchain which is the toolchain used to create your documentation

  • the docToolchain shell wrapper script installed in your project which calls the toolchain

The use of this setup has the following advantages:

  • It’s easy to build your documentation within your project folder.

  • Ensures that everyone in the project uses the same docToolchain version.

  • Keeps all docToolchain technology out of your project repository.

  • Facilitates the installation of the docToolchain if not installed.

  • Makes it easier to upgrade to newer versions of docToolchain.

Install dtcw in your project directory

The docToolchain wrapper script dtcw, respective dtcw.ps1 or dtcw.bat for MS Windows, is meant to be installed in your project root directory. The wrapper script simplifies calls to the docToolchain.

Even if you are going to use docToolchain in multiple projects, the toolchain will only be installed once on your system.
Steps for MacOS/Linux/WSL2 with bash

If you have an Apple Silicon (M1/M2) Mac, make sure that you have docker up and running, rosetta is installed and up-to-date (softwareupdate --install-rosetta) and type the following commands in the Terminal:

`arch -x86_64 /bin/bash`

Now, download dtcw into your project directory and make the script executable with the following commands:

cd <your project>
curl -Lo dtcw https://doctoolchain.org/dtcw
chmod +x dtcw

If you don’t have curl installed, you can also use wget:

cd <your project>
wget doctoolchain.org/dtcw
chmod +x dtcw
Windows with Powershell
cd <your project>
Invoke-WebRequest doctoolchain.org/dtcw.ps1 -Outfile dtcw.ps1
Got an error message that you are not allowed to execute powershell scripts? Try to switch to an unrestricted powershell by executing powershell.exe -ExecutionPolicy Unrestricted.
Windows with cmd.exe
cd <your project>
curl -Lo dtcw.bat doctoolchain.org/dtcw.bat
dtcw.bat wraps the dtcw.ps1 script and executes it in powershell. This might be easier to use if you haven’t yet configured your powershell as a developer.
In case your development team uses different operating systems, put the wrapper scripts for the desired operating systems (dtcw, dtcw.ps1, and dtcw.bat) into your project.

Once the docToolchain wrapper is installed in your project directory you have to decide how to install the toolchain:

docToolchain depends on Java 17

If you don’t use the docToolchain container image you have to install Java on your system. In case you have Java already installed, make sure JAVA_HOME is set.

You may use dtcw to install the correct Java version, as shown in the next steps.

Run docToolchain in a container

The docToolchain project provides a container image of approximately 900 MB from the Docker Hub container registry. The Dockerfile from which the image is created may be found at https://github.com/docToolchain/docker-image.

To run docToolchain in a container you need an installed container engine. The best known container engine is Docker.

If the container engine is installed you can Run your First Command. The docToolchain wrapper script in your project directory will detect the container engine and pull the docToolchain image on the first invocation.

Use your custom docker image

Some might need to create their own docker image to add additional tooling or configurations, e.g. proxy settings. In this case you can pass the image name via parameter image directly after docker:

./dtcw docker image <image_name> generateHTML
.\dtcw.ps1 docker image <image_name> generateHTML
.\dtcw.bat docker image <image_name> generateHTML

Pass environment variables to docker containers

To pass any environment variable to the docker container you can make use of an environment file. The environment file must have the name dtcw_docker.env and must be located in the same folder as dtcw.

An example content is e.g.:

# set environment variables for docToolchain docker container
PROJECT=TEST_PROJECT
TEAM=TEST_TEAM

Pass additional parameter to docker containers

To pass additional parameters to the docker container you can make use of the parameter extra_arguments followed by a string with the additional parameters.

One usecase is to enable you to set environment variables to dynamic values.

./dtcw docker image <image_name> extra_arguments "--env USER=${USERNAME} --env REPO_LOCATION=`git config remote.origin.url`" generateHTML

Install docToolchain with dtcw

Steps for MacOS/Linux/WSL2 with bash

To install docToolchain in $HOME/.doctoolchain execute the following command.

./dtcw install doctoolchain

In case you have no Java installed you may use dtcw to install Java in a subdirectory of $HOME/.doctoolchain.

./dtcw install java
Unable to locate Java Runtime - check your Bash environment

If dtcw complains about not being able to locate a Java Runtime, make sure Java is found in your Bash shell, the shell used by dtcw.

If you use dtcw from another shell like zsh, it may be that your shell finds the supported Java version but your bash setup doesn’t. In that case, please switch to bash and make sure that a supported Java version is found. Afterwards, you can switch back to your shell.
Windows with Powershell

To install docToolchain in $HOME/.doctoolchain execute the following command.

./dtcw.ps1 install doctoolchain

In case you have no Java installed you can use dtcw.ps1 to install Java:

.\dtcw.ps1 install java
Windows with cmd.exe

To install docToolchain in $HOME/.doctoolchain execute the following command.

./dtcw.bat install doctoolchain

In case you have no Java installed you can use dtcw.ps1 to install Java:

.\dtcw.bat install java

If the docToolchain installation finished successfully, you are ready to Run your First Command.

Install docToolchain with SDKMAN!

TODO: description how to install docToolchain with SDKMAN!.

Run your First Command

Call the docToolchain wrapper with tasks --group doctoolchain to show all tasks provided by docToolchain. Those tasks may be used when invoking the docToolchain wrapper script.

The first time docToolchain is called, it downloads all necessary dependencies. Therefore, the execution of the command may take some time. Subsequent calls to docToolchain will be faster. 
./dtcw tasks --group=doctoolchain
dtcw 0.50 - 8061694f
docToolchain 2.3.0
Available docToolchain environments: local (1)
Environments with docToolchain [2.3.0]: local (2)
Using environment: local (3)
Using Java 17.0.6 [/home/john_doe/.doctoolchain/jdk/bin/java] (4)
Downloading https://services.gradle.org/distributions/gradle-7.5.1-bin.zip (5)
..........10%..........20%..........30%...........40%..........50%..........60%..........70%...........80%..........90%..........100%

Welcome to Gradle 7.5.1!

Here are the highlights of this release:
 - Support for Java 18
 - Support for building with Groovy 4
 - Much more responsive continuous builds
 - Improved diagnostics for dependency resolution

For more details see https://docs.gradle.org/7.5.1/release-notes.html

To honour the JVM settings for this build a single-use Daemon process will be forked. See https://docs.gradle.org/7.5.1/userguide/gradle_daemon.html#sec:disabling_the_daemon.
Daemon will be stopped at the end of the build

> Configure project :

Config file '/code/docToolchainConfig.groovy' does not exist' (6)
[ant:input]
[ant:input] do you want me to create a default one for you? (y, n)
y
1 List of available docToolchain environments. The output may vary depending on your system. In our example only the local environment is available since neither sdk nor docker was found.
2 Environments in which docToolchain s available. The output may vary depending on how you installed docToolchain. In our example docToolchain was found in the user’s local environment in $HOME/.doctoolchain.
3 Shows the used docToolchain environment. In case docToolchain is installed in more than one environment the wrapper script picks the environment in the following order: local, sdk, and then docker.
4 Location of the used Java. In our example Java was installed in the local environment with the docToolchain wrapper script.
5 docToolchain was invoked the first time, thus it is downloading its dependencies.
6 The docToolchain configuration file docToolchainConfig.groovy wasn’t found in the project repository. docToolchain asks if it should create a new one. 
.\dtcw.ps1 tasks --group=doctoolchain
dtcw.bat tasks --group=doctoolchain
If you are behind a corporate proxy, you might need to consider build-script dependencies are fetched from a repository referenced by the property mavenRepository. By default, the value https://plugins.gradle.org/m2/ is used. When a repository requiring credentials is used the properties mavenUsername and mavenPassword can be set as well.
Example command passing a custom maven repository with credentials from the command line
DTC_OPTS="-PmavenRepository=your_maven_repo -PmavenUsername=your_username -PmavenPassword=your_pw" ./dtcw tasks --group=doctoolchain --info

Configure docToolchain to Use Existing Documents

If your project already has documents in AsciiDoc format, you’ll need to tell docToolchain where to find them.

To do so, take a look at the created docToolchainConfig.groovy and update it.

Create a New Documentation Project from Scratch with Arc42

If you want to use the arc42 template in your project, you can get it in AsciiDoc format by using the following commands.

Linux / WSL2 with bash
./dtcw downloadTemplate
Windows with Powershell
.\dtcw.ps1 downloadTemplate
Windows with cmd.exe
dtcw.bat downloadTemplate

Generate HTML and PDF

By now, the docToolchain wrapper dtcw should be in your project folder along with the arc42 template.

Now Let’s render arc42 to HTML and PDF. To do so, run the commands below:

Linux / WSL2 with bash
./dtcw generateHTML
./dtcw generatePDF
Windows
.\dtcw.ps1 generateHTML
.\dtcw.ps1 generatePDF

As a result, you will see the progress of your build together with some warnings which you can just ignore for the moment.

The first build generated some files within the build:

build
|-- html5
|   |-- arc42
|   |   `-- arc42.html
|   `-- images
|       |-- 05_building_blocks-EN.png
|       |-- 08-Crosscutting-Concepts-Structure-EN.png
|       `-- arc42-logo.png
`-- pdf
    |-- arc42
    |   `-- arc42.pdf
    `-- images
        |-- 05_building_blocks-EN.png
        |-- 08-Crosscutting-Concepts-Structure-EN.png
        `-- arc42-logo.png

Congratulations! If you see the same folder structure, you’ve just rendered the standard arc42 template as HTML and PDF!

Please raise an issue on github if you didn’t get the right output.

Blog-Posts: Behind the great Firewall, Enterprise AsciiDoctor

Upgrading to a New docToolchain Release

If there is a new docToolchain release you wish to use, do the following:

  1. Open the docToolchain wrapper script (dtcw, respective dtcw.ps1 and dtcw.bat) in your favorite text editor and look for the line with DTC_VERSION which should be located near the start of the file:

# See https://github.com/docToolchain/docToolchain/releases for available versions.
# Set DTC_VERSION to "latest" to get the latest, yet unreleased docToolchain version.
VERSION=2.1.0

  1. Change it to match the desired release.

  2. In case you want to install docToolchain in local user environment install the new docToolchain release with the following command:

./dtcw install doctoolchain

  1. If you want to test a not-yet-released feature, you can set the DTC_VERSION to latest and dtcw will clone or pull the current default branch of the project. Please note this only works with a local copy, not with a Docker install.

  2. If you want to develop new features for docToolchain, you can also use latestdev as version. In this case, dtcw will try to clone the docToolchain repository with the ssh-git protocol to a fork in $HOME/.doctoolchain/docToolchain-latest.

latest and latestdev currently only work with the bash version of the wrapper.