Build with Docker
Last modified: 07 January 2025Writerside maintains a Docker image that runs the documentation builder. While local builds 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, GitLab, and TeamCity all include a build step using the Docker image.
Pull Docker builder image
The Docker image with the Writerside builder is available in Docker Hub and in the JetBrains Docker Registry.
The tag for the latest writerside-builder
image is 243.22562.
docker pull jetbrains/writerside-builder:243.22562
docker pull registry.jetbrains.team/p/writerside/builder/writerside-builder:243.22562
note
Further instructions assume that you pulled the image from Docker Hub. If you pulled it from the JetBrains Docker Registry, replace
jetbrains/writerside-builder
withregistry.jetbrains.team/p/writerside/builder/writerside-builder
.
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:
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:243.22562
Alternatively, you can use an env file to define the variables:
docker run --rm -v .:/opt/sources --env-file=builder.env \
jetbrains/writerside-builder:243.22562
Where builder.env is a file that sets the variables to specific values:
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 -v
option.
When the builder finishes, --rm
removes the container. You should find the output in the output directory under the project root.
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:
docker run --rm -v .:/opt/sources \
jetbrains/writerside-builder:243.22562 \
/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 runningXvfb :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:
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:
--source-dir
,-i
Specify the directory with documentation sources. When using variables, specify it via
SOURCE_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 settings to generate a PDF. If not specified, the builder produces a regular documentation website. When using variables, specify it via
PDF
.
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.
Create a Dockerfile with the following contents:
FROM jetbrains/writerside-builder:243.22562 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 startingXvfb
happens in the sameRUN
directive as launching the/opt/builder/bin/idea.sh
script.Build an image from this Dockerfile. In the directory with the Dockerfile, run the following command:
docker build -t help-website .
Run a container from this image in the documentation root and publish port 80 in the container to 8080 on the host.
docker run -dit -p 8080:80 help-website
Now you can visit 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.