The idea is to host a docs archives site that will host all the versions that are no longer supported. - https://gitlab.com/gitlab-org/gitlab-docs-archives - https://archives.docs.gitlab.com/ ## Why not use `gitlab-docs` to do this? We can lift the size limit now https://docs.gitlab.com/ee/user/admin_area/settings/continuous_integration.html#maximum-artifacts-size, so this is not an issue. The problem is that we use [`docs:latest`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/05218c6687877105dcdd1e147a7b601f6e176ce4/.gitlab-ci.yml#L493) to deploy the site **every** time, so, the bigger the size, the more time it takes to deploy, and the more bandwidth we use to download the image (which means more money). By having a separate project for the archives means that we don't care about the size, time to deploy, bandwidth, etc., since we deploy once a month. ## Implementation details A high level of steps to implement the archives site: 1. [x] Add a new subdomain of `docs.gitlab.com`, for example `https://archives.docs.gitlab.com`, or register a different domain. Infrastructure would help us with this. https://gitlab.com/gitlab-com/gl-infra/reliability/-/issues/16053 1. [x] Create a new project that will host the archived images and be set up with Pages 1. [x] [Set up the new domain with Pages](https://docs.gitlab.com/ee/user/project/pages/custom_domains_ssl_tls_certification/#steps) 1. [x] Use the [`archives Dockerfile`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/dockerfiles/archives.Dockerfile) to gather the archived versions in one Docker image, and create a CI job to use the archives Docker image and push the archives to GitLab Pages. At this point, we should have docs deployed under `https://archives.docs.gitlab.com/14.2/` for example. https://gitlab.com/gitlab-org/gitlab-docs-archives/-/issues/1 1. [x] In the archives site, in the versions dropdown show only the current version and the archives page https://gitlab.com/gitlab-org/gitlab-docs/-/issues/1290 1. [x] Increase Pages and artifacts [size limit](https://docs.gitlab.com/ee/user/admin_area/settings/continuous_integration.html#maximum-artifacts-size) (needed for big-sized Pages sites) https://gitlab.com/gitlab-com/gl-infra/reliability/-/issues/16811 1. [x] Build a lunr.js Docker image https://gitlab.com/gitlab-org/gitlab-docs/-/issues/1255 1. [x] Update index.html to show information about the archives site: https://gitlab.com/gitlab-org/gitlab-docs-archives/-/issues/3 1. [x] Redirect offline versions to the archives site. Two options here: 1. [x] It'll work fine: https://gitlab.com/gitlab-org/gitlab-docs/-/issues/1293+ 1. [ ] Ideally: https://gitlab.com/gitlab-org/gitlab-pages/-/issues/601+ 1. [x] Create a 404 page for the archives site https://gitlab.com/gitlab-org/gitlab-docs-archives/-/issues/6 1. [ ] Optional. Create a Container Registry cleanup policy for the Docker images that will move to the archives https://gitlab.com/gitlab-org/gitlab-docs/-/issues/1286 When all the above is implemented, links in a self-managed instance running 14.2 will follow the following journey: 1. Link in GitLab: `https://gitlab.example.com/help/install/index.md` 1. GitLab redirects to: `https://docs.gitlab.com/14.2/ee/install/index.html` 1. Docs site Pages redirects to: `https://archives.docs.gitlab.com/14.2/ee/install/index.html` ## Advantages - We have a way to automagically redirect the help links inside old, unsupported GitLab versions to the archives docs site. - We don't break any links. - Users/customers don't need to spin up their own docs site and set up anything. ## Caveats - ~~No search capability.~~ We will use lunr.js. - Since we'll be gathering all the archived versions in one Docker image, its size would get bigger over time. Which also means we would have to download the archives image once a month, and then push all the files to GitLab Pages. This is related to https://gitlab.com/gitlab-org/technical-writing/-/issues/509+.