Skip to content

Avoid setting up documentation in Docker image

Evan Read requested to merge eread/avoid-setting-up-docs-in-docker-image into main

What does this MR do and why?

Following up from: !4366 (merged), we end up with two gitlab-docs directories:

  • The first from our Dockerfile at $HOME/source. That has has the documentation already added to it, and you can just run make compile.
  • The second seems to be a Workspaces thing and is at /projects/gitlab-docs. The second directory needs make setup still to work. That pulls all the documentation down a second time into the running Workspace.

It seems like we can't avoid running make setup in the running Workspace anyway, so I'm proposing here that we don't try and set up in $HOME/source.

When someone tries to run make compile, they get the warning about make setup anyway, so the user experience shouldn't be too bad. In addition, by not pulling docs into the image:

  • The image is a lot smaller.
  • The docs won't get stale in the image.
  • You can work on gitlab-docs changes and not have content if you don't need content.

Probably the only UX problem might be that you can run make setup and make compile, and still not have content (just the scaffolding around the content), which you might not expect. So I've added some warnings to the build to explain that docsare missing. This will mean that in CI/CD pipelines where we don't expect all the docs, we'll be surfacing warnings, but I don't think that's a bad idea.

How to set up and validate locally

  1. Check out this branch.
  2. Run docker buildx build --file dockerfiles/gitlab-docs-workspace.Dockerfile . --build-arg ASDF_VERSION="0.13.1".
  3. Run docker run -ti --rm <image ID> bash. In the running container:
    1. Run cd ~.
    2. Run git clone --branch eread/avoid-setting-up-docs-in-docker-image https://gitlab.com/gitlab-org/gitlab-docs.git.
    3. Run cd gitlab-docs.
    4. Run make setup.
    5. Run make compile. Notice the new warnings.
    6. Run bundle exec rake clone_repositories.
    7. Run make compile. Notice lack of warnings.

I'm still not sure that make view is working well with the settings we have, but we can fix that in a follow up.

Merge request acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Evan Read

Merge request reports