# Build with Docker

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/help/writerside/llms.txt).

Writerside maintains a Docker image that runs the documentation builder. While [local builds](local-build.html) rely on the bundled builder, with Docker, you can specify the tag of any publicly available builder version.

This can be useful if you updated to a new version of Writerside that processes some markup differently, and you are not ready to change the sources yet to make it compatible with the latest version. Then you can run builds with the previous builder version. Or you can use it to see if the new builder will work in your project before updating to the latest version of Writerside.

You can use the Docker builder to create a script for automating your documentation builds both locally and on a CI/CD pipeline. For example, our instructions for [GitHub](deploy-docs-to-github-pages.html), [GitLab](deploy-docs-to-gitlab-pages.html), and [TeamCity](build-on-teamcity.html) all include a build step using the Docker image.

Procedure: Pull Docker builder image

The Docker image with the Writerside builder is available in [Docker Hub](https://hub.docker.com/) and in the JetBrains Docker Registry.

The tag for the latest `writerside-builder` image is 2026.08.0328.

Docker Hub:

```SHELL
docker pull jetbrains/writerside-builder:2026.08.0328
```

JetBrains Docker registry:

```SHELL
docker pull registry.jetbrains.team/p/writerside/builder/writerside-builder:2026.08.0328
```

> **Note:**
> Further instructions assume that you pulled the image from [Docker Hub](https://hub.docker.com/). If you pulled it from the JetBrains Docker Registry, replace `jetbrains/writerside-builder` with `registry.jetbrains.team/p/writerside/builder/writerside-builder`.

Procedure: Run Docker builder container

When running a container from this image, mount the project sources directory (and an optional separate output directory) into the container and specify the necessary environment variables. For example, when running from the Starter documentation project root:

```SHELL
docker run --rm -v .:/opt/sources \
-e SOURCE_DIR=/opt/sources \
-e MODULE_INSTANCE=Writerside/hi \
-e OUTPUT_DIR=/opt/sources/output \
-e RUNNER=other \
-e PDF=PDF.xml \
jetbrains/writerside-builder:2026.08.0328
```

Alternatively, you can use an [env file](https://docs.docker.com/reference/cli/docker/container/run/#env) to define the variables:

```SHELL
docker run --rm -v .:/opt/sources --env-file=builder.env \
jetbrains/writerside-builder:2026.08.0328
```

Where `builder.env` is a file that sets the variables to specific values:

```PLAINTEXT
SOURCE_DIR=/opt/sources
MODULE_INSTANCE=Writerside/hi
OUTPUT_DIR=/opt/sources/output
RUNNER=other
PDF=PDF.xml
```

In the previous examples, `-v .:/opt/sources` mounts the current directory (you should be running `docker run` from the project root) to the directory `/opt/sources` in the container. If you want to output the built artifacts to a different directory, add a separate mount using another `-v` option.

When the builder finishes, `--rm` removes the container. You should find the output in the `output` directory under the project root.

> **Note:**
> If you want to build multiple instances as a single documentation website, set the `IS_GROUP=true` environment variable. In this case, the `MODULE_INSTANCE` variable should contain the build group ID.
>
>
>
> For more information, see [Build groups](build-groups.html).

## Builder options and variables

By default, the Docker container runs the `helpbuilderinspect` command with option values from the provided environment variables. You can also run the `helpbuilderinspect` command directly when running the container, but then instead of environment variables, provide the necessary options to the command:

```SHELL
docker run --rm -v .:/opt/sources \
jetbrains/writerside-builder:2026.08.0328 \
/bin/bash -c "
export DISPLAY=:99 &&
Xvfb :99 &
/opt/builder/bin/idea.sh helpbuilderinspect \
--source-dir /opt/sources \
--product Writerside/hi \
--output-dir /opt/sources/output \
--runner other \
-pdf PDF.xml \
"
```

> **Note:**
> The container first has to prepare the environment by setting the `DISPLAY` variable to `:99` and running `Xvfb :99` in the background to emulate a physical display on a virtual machine.

When using variables, the container runs the command in quotes taking option values from the provided variables, like this:

```SHELL
export DISPLAY=:99 &&
Xvfb :99 &
/opt/builder/bin/idea.sh helpbuilderinspect \
--source-dir %SOURCE_DIR% \
--product %MODULE_INSTANCE% \
--output-dir %OUTPUT_DIR% \
--runner %RUNNER% \
-pdf %PDF%
```

The following options are required:

`--product`, `-p`
: Specify the [module](help-modules.html) and [instance](instances.html) that you want to build, separated by a slash `/`. When using variables, specify it via `MODULE_INSTANCE`.
:
:
:
: > **Note:**
: > If you want to [build multiple instances](build-groups.html), use [--group or -g](#group) instead.

`--group`, `-g`
: Specify the [module](help-modules.html) and [build group](build-groups.html) that you want to build, separated by a slash `/`. When using variables, set `IS_GROUP=true` and specify the build group ID via `MODULE_INSTANCE`.
:
:
:
: > **Note:**
: > Do not use it together with the [--product](#product) option.

`--source-dir`, `-i`
: Specify the directory with documentation sources. When using variables, specify it via `SOURCE_DIR`.

`--output-dir`, `-o`
: Specify the output directory for the generated documentation. When using variables, specify it via `OUTPUT_DIR`.

The following options are not required:

`--runner`, `-r`
: Specify the environment or platform on which the builder will be executed. The supported values are case-insensitive and include:
:
:
:
: * `teamcity`: Produce artifacts specific for TeamCity (default value).
:
: * `gitlab`: Produce artifacts specific for GitLab.
:
: * `github`: Produce artifacts specific for GitHub.
:
: * `other`: Produce generic artifacts that may require some adjustments for your environment.
:
:
:
: When using variables, specify it via `RUNNER`.

`-pdf`
: Specify the file with [PDF export](export-to-pdf.html) settings to generate a PDF. If not specified, the builder produces a regular documentation website. When using variables, specify it via `PDF`.

Procedure: Example: Create builder image with the generated website

Let's say you want to create your own Docker image that builds a specific instance with a specific builder version and also starts a webserver with the produced website when you run a container from this image.

1. Create a Dockerfile with the following contents:

```DOCKERFILE
FROM jetbrains/writerside-builder:2026.08.0328 as build

ARG INSTANCE=Writerside/hi

RUN mkdir /opt/sources

WORKDIR /opt/sources

ADD Writerside ./Writerside

RUN export DISPLAY=:99 && \
Xvfb :99 & \
/opt/builder/bin/idea.sh helpbuilderinspect --source-dir /opt/sources --product $INSTANCE --runner other --output-dir /opt/wrs-output/

WORKDIR /opt/wrs-output

RUN unzip -O UTF-8 webHelpHI2-all.zip -d /opt/wrs-output/unzipped-artifact

FROM httpd:2.4 as http-server

COPY --from=build /opt/wrs-output/unzipped-artifact/ /usr/local/apache2/htdocs/
```

> **Warning:**
> It is critical that setting the `DISPLAY` variable and starting `Xvfb` happens in the same `RUN` directive as launching the `/opt/builder/bin/idea.sh` script.

2. Build an image from this Dockerfile. In the directory with the Dockerfile, run the following command:

```SHELL
docker build -t help-website .
```

3. Run a container from this image in the documentation root and publish port 80 in the container to 8080 on the host.

```SHELL
docker run -dit -p 8080:80 help-website
```

Now you can visit [http://localhost:8080](http://localhost:8080) to see the built help website being served by an HTTP server in the container.

If you want to use another builder version or build a different instance, change it in the Dockerfile, rebuild the image, and run the container. Remember to change the ZIP archive name as it contains the instance ID in capital letters: `webHelpHI2-all.zip`.