Document how to support multi versions for docs using environments
Problem to solve
There is a need to hold multiple docs sites in order to serve different customers that use different versions.
Intended users
Any user that wishes to hold several versions of a website/documentation per version.
Proposal
Use our existing CI/CD and environments to hold multiple versions per release branch. Release branches should match a regular expression so that you can use it with environments.
- Documentation for release 12.2 would sit under 12.2
- Documentation for release 12.3 would sit under 12.3
- Documentation for release 12.4 would sit under 12.4
- and so one.....
Example one - Use review apps
Here is an example of how this can be done - https://gitlab.com/krasio/vdocs/blob/master/.gitlab-ci.yml.
In short CI is configured in a way so that on push to master
or "version" branches it will build a static site and then deploy it to the respective path. The easiest way is to deploy the site and its versions on your own server using a runner with the shell executor, and NGINX serving the site. See an example configuration at https://gitlab.com/gitlab-examples/review-apps-nginx/.
In the example above we use rsync
over SSH but it can be anything that will work for the user. There is also on_stop
job defined that will remove the files in case branch is deleted (or when run manually). The root is symlinked to the versions for the master
branch, it will be easy to make the default configurable (for example using CI variable). Each deployment also creates an environment - https://gitlab.com/krasio/vdocs/environments.
The result directory structure looks like this
1.0/
index.html -> ./master/index.html
master/
The root URL is http://vdocs.codingspree.net/ and respective versions are under http://vdocs.codingspree.net/master, http://vdocs.codingspree.net/1.0, etc...
Pros:
- No size limitation
- Only single version is generated and deployed (
rsync
will pick just the files that changed). - Pretty flexible
Cons:
- Users need to bring their own hosting/deployment script
- Unlike Pages, no easy to setup access control
- Unlike Pages, no Let's Encrypt integration, users should handle SSL certs and config on their own.
Example two - Use Pages
Another (a bit naive) approach to do this using Pages - https://gitlab.com/krasio/versioned-docs/blob/master/.gitlab-ci.yml.
On every push to the master or one of the "version" branches it will build the site for all of them and the then publish it to Pages - https://krasio.gitlab.io/versioned-docs/.
Pros:
- Built in hosting/deployment that comes from Pages
- Built in access control
- Built in Let's Encrypt integration
Cons:
- Will get slow when there are many versions
- Eventually will hit Pages' size limit