Build with Docker
Writerside 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.
The Docker image with the Writerside builder is hosted in the JetBrains Docker registry. The tag for the writerside-builder image that is bundled with the current Writerside version is 241.18775. You can pull it using the following command:
When you run a container from this image, mount the project sources directory (and an optional separate output directory) into the container and run the helpbuilderinspect command, which launches the CLI builder. For example, if you want to build the default instance with id HI in the starter project, run the following command from the project root:
This command does the following:
Mounts the current directory (you should be running it 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
-voption.Runs the container from the
writerside-builderimage with tag241.18775.The container first prepares the environment by setting the
DISPLAYvariable to:99and runningXvfb :99in the background to emulate a physical display on a virtual machine.Then it runs the
/opt/builder/bin/idea.shscript with thehelpbuilderinspectcommand and options that specify directories with the sources and output, and the instance to build.When it is done, Docker removes the container. You should find the output in the output directory under the project root.
The helpbuilderinspect command has the following options:
--source-dir,-iSpecify the directory with documentation sources.
--product,-pSpecify the module and instance that you want to build, separated by a slash
/.--runner,-rSpecify the environment or platform on which the builder will be executed. The supported values are case-insensitive and include:
teamcity: This is the default value that produces artifacts specific for TeamCity.gitlab: Produce artifacts specific for GitLab.github: Produce artifacts specific for GitHub.other: Produce generic artifacts that may require some adjustments for your environment.
--output-dir,-oSpecify the output directory where the generated documentation will be stored.
Builder image with a specific version
Let's say you want to create an image with the builder of a specific version that already contains the build command that the container should run. Then in the docker run command, you will only need to mount the correct source and output directories and provide a variable with the module name and ID.
Create a Dockerfile with the following contents:
FROM registry.jetbrains.team/p/writerside/builder/writerside-builder:241.18775 CMD export DISPLAY=:99 && \ Xvfb :99 & \ /opt/builder/bin/idea.sh helpbuilderinspect --source-dir /opt/sources --product $INSTANCE --runner other --output-dir /opt/sources/outputBuild an image from this Dockerfile. In the directory with the Dockerfile, run the following command:
docker build -t wrs-builder-241.18775 .Now you can run a container from this image every time you want to build an instance using the builder version 241.18775. Make sure to mount the project directory to /opt/sources in the container and set the
INSTANCEenvironment variable to a string that contains the module name and instance ID separated by a slash/. For example, run the following command from the project root directory:docker run --rm -v .:/opt/sources -e INSTANCE='Writerside/hi' wrs-builder-241.18775
The builder output should appear in the output directory under the project root.
If you want to use another builder version, change it in the Dockerfile, rebuild the image, and specify the new image name in the docker run command.
Builder image with the generated website
Let's say you want an 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 registry.jetbrains.team/p/writerside/builder/writerside-builder:241.18775 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/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 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.