Continue to produce our own complete documentation Docker images?
For a long time, the Technical Writing in GitLab team has managed our own complete documentation Docker images, which are:
- Configured at: https://gitlab.com/gitlab-org/gitlab-docs/-/tree/main/dockerfiles?ref_type=heads.
- Deployed to: https://gitlab.com/gitlab-org/gitlab-docs/container_registry.
There are advantages and disadvantages to this approach.
Advantages
Maintaining our own complete documentation Docker images allows the Technical Writing in GitLab team to:
- Make a Runner execution environment with only (but all) the tooling we need.
- Fully rely on something we host locally, which is unlikely to become unavailable unexpectedly.
- Develop custom tests to test changes to our Docker image files before we use them.
- Split our requirements into different images, to keep the images small and efficient.
- The source of truth for versions is kept in one place: https://gitlab.com/gitlab-org/gitlab-docs/-/blob/a0d3a63a54084481e50ee9bf37c935ed95011480/.gitlab-ci.yml#L21.
Disadvantages
Maintaining our own complete documentation Docker images does come with some disadvantages:
- Our team must spend time developing and maintaining the Docker images.
- Because our tooling is embedded in the Docker images, new images must be configured, deployed, and then configured in all the documentation projects that use them. This has become quite a long and complex process: https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab/issue_templates/Ruby%20Alpine%20versions%20bump.md that is not particularly well-known within the Technical Writing in GitLab team, let alone outside of the team.
- Though we've split our requirements into many different images, you could argue that they're still too big for individual tests which isn't as efficient as it could be.
- The single source of truth is difficult to share among projects, which have their own sources of truth for dependencies (like
package.json
andGemfile
files).
Options
Some options to discuss.
Option 1: Continue with our own complete documentation Docker images
This option requires minimal changes, though we'd probably either:
- Update https://gitlab.com/gitlab-org/technical-writing-group/gitlab-docs-hugo with
Dockerfile
files. - Host in https://gitlab.com/gitlab-org/gitlab-build-images.
It might be possible to automate many of the steps required to roll out these new images. For example, perhaps a process that automatically raises a bunch of MRs when a new documentation Docker image is published.
This option has all the advantages and disadvantages from above.
Option 2: Create a new minimal documentation Docker image
This option requires more thought about what should be the responsibility of the Docker image, and what should each pipeline job bring?
At the moment, pipeline jobs for documentation tests don't need to do anything other than execute commands. Everything prerequiste is available in the Docker image, so runtime is minimal and quick.
In this new option, only large dependencies are met by the Docker image, and each project and pipeline job brings the rest. For example:
- Docker image brings Node.js and
yarn
dependencies. - Project brings
markdownlint
and Vale dependencies.
This option addresses some of the disadvantages above, and keeps some of the advantages.
Option 3: No longer maintain a documentation Docker image
This option is similar to option 2, except instead of Technical Writing in GitLab looking after a minimal documentation image, we either:
- Use whatever Docker image the project that runs our tests provides. These are usually sourced from: https://gitlab.com/gitlab-org/gitlab-build-images
- Rely on upstream images published by our tool makers. For example, official Node.js images.