Install docToolchain

Prerequisites

  • Java 17, 21 or 25 — check with java -version (./dtcw4 local install java installs Java 25 for you)

  • git — needed to clone docToolchain during installation

  • Bash — dtcw4 is a Bash script (on Windows, use WSL2)

Quick Start

1. Get the Wrapper Script

Download dtcw4 into your project directory:

cd <your project>
curl -Lo dtcw4 https://doctoolchain.org/dtcw4
chmod +x dtcw4
On Windows, use WSL2. dtcw4 is a Bash script.

2. Install docToolchain

# Install Java if needed
./dtcw4 local install java

# Install docToolchain v4
./dtcw4 local install doctoolchain

This clones the main-4.x branch and builds the runtime JARs once (~2 min). After that, no build tool is involved at runtime.

3. Download a Template (optional)

First, create a config file if you don’t have one yet:

touch docToolchainConfig.groovy
./dtcw4 local downloadTemplate

This interactively installs the arc42 architecture template and updates your config file.

4. Generate Output

./dtcw4 local generateHTML
./dtcw4 local generatePDF
./dtcw4 local generateSite

Output is written to the build/ directory:

build/
├── html5/          # generateHTML output
├── pdf/            # generatePDF output
└── microsite/
    └── output/     # generateSite output

5. List All Tasks

./dtcw4 tasks

How It Works

Only dtcw4 lives in your project directory. It handles:

  1. Installation: Clones docToolchain from GitHub and builds the runtime JARs once.

  2. Task execution: Delegates to the installed dtcw in ~/.doctoolchain/docToolchain-4.0.0/, which runs tasks directly via the JVM — no Gradle, no daemon.

Runtime JARs are stored in ~/.doctoolchain/docToolchain-4.0.0/lib/. Task execution uses direct JVM invocation (~2-3s startup).

Running in Docker

docToolchain provides a container image from Docker Hub:

./dtcw4 docker generateHTML

The wrapper script detects the container engine and pulls the image automatically.

Custom Docker Image

./dtcw4 docker image <image_name> generateHTML

Environment Variables for Docker

Create a file dtcw_docker.env in your project directory:

PROJECT=MY_PROJECT
TEAM=MY_TEAM

Updating

./dtcw4 local install doctoolchain --update

This pulls the latest main-4.x and rebuilds the runtime JARs.

Environment Variables

Variable Default Description

DTC_VERSION

4.0.0

docToolchain version to use

DTC_V4_BRANCH

main-4.x

Git branch to install from

DTC_HEADLESS

auto-detected

Set to true for non-interactive mode (CI/CD)

DTC_CONFIG_FILE

docToolchainConfig.groovy

Path to configuration file

DTC_SITETHEME

(none)

URL to an external microsite theme zip