Deploy an archives docs site to host old GitLab docs versions
The idea is to host a docs archives site that will host all the versions that are no longer supported.
gitlab-docs
to do this?
Why not use 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
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:
-
When we implement lunr.js (gitlab-docs!2754 (closed)), we should build two Docker images with each doc release each month: - Have conditionals in our Nanoc layouts, for example:
- When
NANOC_ENV=production
is used, Algolia would be the search engine. Used bydocs.gitlab.com
. - When
NANOC_ENV=archives
is used, lunr.js would be used. Used byarchives.docs.gitlab.com
.
- When
- Update the
.gitlab-ci.yml
file to add one more job and build the archived version pushed to a new registry folder (registry.gitlab.com/gitlab-org/gitlab-docs/archives
).
- Have conditionals in our Nanoc layouts, for example:
-
Add a new subdomain of docs.gitlab.com
, for examplehttps://archives.docs.gitlab.com
, or register a different domain. Infrastructure would help us with this. -
Create a new project that will host the archived images and be set up with Pages, and lift the maximum artifacts size (needed for big-sized pages sites). -
Set up the new domain with Pages -
Use the archives Dockerfile
to gather the archived versions in one Docker image. -
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. -
In self-managed, set the Documentation Pages URL to https://docs.gitlab.com
by default gitlab#350671 (closed) (you could still override it). -
In gitlab-docs
, add the old version inredirects.yaml
as splat redirects, for example:- from: /14.2/* to: https://archives.docs.gitlab.com/14.2/:splat
When all the above is implemented, links in a self-managed instance running 14.2 will follow the following journey:
- Link in GitLab:
https://gitlab.example.com/help/install/index.md
- GitLab redirects to:
https://docs.gitlab.com/14.2/ee/install/index.html
- Docs site Pages redirects to:
https://archives.docs.gitlab.com/14.2/ee/install/index.html
Some thoughts about the archives site:
- In the versions dropdown show only the current version and the archives page.
Cons of having "duplicate" images:
- We build things twice. More space use in the registry, which means more money spent. Each Docker image has a compressed size of about ~150M (and increasing)
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 can use lunr.js gitlab-docs!2754 (closed) - Since we'll be gathering all the 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 Q4FY2022 KR: Determine how to improve/remedy th... (#509 - closed).