Improve docs for running archive container images on MacOS

We provide directions for testing our Archive images locally here: https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/releases.md?ref_type=heads#optional-test-locally

We can improve a few things with this documentation:

  • You need to include search-related build-args to have a working site (#1765 (comment 1773606935))
  • docker build fails often with segfaults when building ruby gems (like these: https://gitlab.com/-/snippets/3673562#L312)
    • fix: remove the failed build and just try it again
  • docker run fails often with nginx errors like this: 2024/02/13 17:24:10 [emerg] 21#21: io_setup() failed (38: Function not implemented) (full output: $3676322)
    • fix: in my case, clearing disk space (maybe not. this seemed to work once but is not making a difference today.)
  • To emulate a self-hosted docs instance, you need to modify /etc/hosts to use a different domain name
  • Running an image from the remote registry fails with the same nginx errors described above
    • fix: not sure
  • Include a recommended docker/colima configuration (you need more resources than the default to build these)
  • docker build throws lots of warnings like this: "The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested"
    • fix: not sure. Putting export DOCKER_DEFAULT_PLATFORM=linux/amd64 in ~/.zshrc seemed to work at one point but maybe no longer does. Adding the platform flag to docker build does not make a difference (docker build --platform linux/amd64 ....)

We need to be able to test these images in order to support self-hosted docs sites (e.g, to test an MR like !4598 (merged)).

Edited by Sarah German