Writerside Help

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.16003. You can pull it using the following command:

docker pull registry.jetbrains.team/p/writerside/builder/writerside-builder:241.16003

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:

docker run --rm -v .:/opt/sources \ registry.jetbrains.team/p/writerside/builder/writerside-builder:241.16003 \ /bin/bash -c " export DISPLAY=:99 && Xvfb :99 & /opt/builder/bin/idea.sh helpbuilderinspect \ --source-dir /opt/sources \ --product Writerside/hi \ --runner other \ --output-dir /opt/sources/output "

This command does the following:

  1. 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 -v option.

  2. Runs the container from the writerside-builder image with tag 241.16003.

  3. The container first prepares 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.

  4. Then it runs the /opt/builder/bin/idea.sh script with the helpbuilderinspect command and options that specify directories with the sources and output, and the instance to build.

  5. 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, -i

Specify the directory with documentation sources.

--product, -p

Specify the module and instance that you want to build, separated by a slash /.

--runner, -r

Specify 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, -o

Specify 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.

  1. Create a Dockerfile with the following contents:

    FROM registry.jetbrains.team/p/writerside/builder/writerside-builder:241.16003 CMD export DISPLAY=:99 && \ Xvfb :99 & \ /opt/builder/bin/idea.sh helpbuilderinspect --source-dir /opt/sources --product $INSTANCE --runner other --output-dir /opt/sources/output
  2. Build an image from this Dockerfile. In the directory with the Dockerfile, run the following command:

    docker build -t wrs-builder-241.16003 .
  3. Now you can run a container from this image every time you want to build an instance using the builder version 241.16003. Make sure to mount the project directory to /opt/sources in the container and set the INSTANCE environment 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.16003

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.

  1. Create a Dockerfile with the following contents:

    FROM registry.jetbrains.team/p/writerside/builder/writerside-builder:241.16003 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 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/
  2. Build an image from this Dockerfile. In the directory with the Dockerfile, run the following command:

    docker build -t help-website .
  3. 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.

Last modified: 19 June 2024