Linux web

This repo follows https://how-to.docs.cern.ch.

• linux is the production site and it must always use the default master branch as a Git Reference on the BuildConfig.

  • linux-qa will use the Git Reference on the latest feature branch, as it changes with every CI job nor on master branch.

• We have a CNAME registered that we then use for a redirect, i.e. linux-qa.cern.ch -> linux-qa.web.cern.ch, to replicate the old website behaviour.

  • Redirection is done with a simple nginx redirection, deployed with oc create -f nginx-redirect-(qa/prod).yaml.

• For https://linux-qa.web.cern.ch and https://linux.web.cern.ch we use KB0006299 solution for a Let's encrypt certificate.

• This repo adds some useful redirections to ease with any old URL format. Check nginx-default-cfg/redirect.conf file for more details. This directory and its contents follow the documentation

Customisations

• /theme directory is used as the Material Design custom_dir for overriding the theme.

• We use https://gitlab.cern.ch/linuxsupport/websites/updates-autogeneration-plugin/ for autogenerating, ordering and adding to our navigation all distribution updates.

CI/CD

Instead of relying on webhooks as suggested by https://how-to.docs.cern.ch, we run builds on CI so we can notice whether they fail or not.

This requires setting up a service account on each namespace:

oc login openshift.cern.ch
oc project linux-qa
oc create sa openshift-operations
oc policy add-role-to-user admin system:serviceaccount:linux-qa:openshift-operations
oc sa get-token openshift-operations
# Note the token on https://gitlab.cern.ch/groups/linuxsupport/-/settings/ci_cd -> LINUXWEB_QA_OPENSHIFT. REMEMBER TO SELECT MASK VARIABLE!!!
oc project linux
oc create sa openshift-operations
oc policy add-role-to-user admin system:serviceaccount:linux:openshift-operations
oc sa get-token openshift-operations
# Note the token on https://gitlab.cern.ch/groups/linuxsupport/-/settings/ci_cd -> LINUXWEB_PROD_OPENSHIFT. REMEMBER TO SELECT MASK VARIABLE!!!

Known issues and limitations

• Due to the size of our documentation we need to edit the corresponding BuildConfig object with specific limits so it does not use the default ones:

# Edit the buildconfig object
oc edit buildconfig linux-docs

# Add the following section:
spec:
  (...)
  resources:
    limits:
      memory: 1Gi
    requests:
      memory: 512Mi

Archive

Following a similar setup (except for the nginx-redirect as this one is not necessary) we have prepared https://gitlab.cern.ch/linuxsupport/websites/linux-archive.web.cern.ch for archiving old content. This helps reducing the building time, as for example splitting old SLC6 updates in a different project.

Upgrading or updating MkDocs configuration

As of August 2021 we still use https://gitlab.cern.ch/authoring/documentation/s2i-mkdocs-container which is now considered unmaintained.

If we ever update the image version, we need to follow certain steps:

• Check the MkDocs and Material design theme version that match the mkdocs Docker image that you will be using.
  • For example, for the 1.3 version, check https://gitlab.cern.ch/authoring/documentation/s2i-mkdocs-container/-/blob/1.3/Dockerfile
• Check if there is any incompatibility of such version with the website by using a feature branch.
• More than probably you will find styling not to be working properly.
  • Update the theme/partials/{footer,header}.html content with the corresponding version of the Material design you got from the previous Dockerfile
    • For 1.3 we copy https://raw.githubusercontent.com/squidfunk/mkdocs-material/7.1.7/src/partials/header.html and adapt as comments mention. Do a diff to check what needs to be moved or added, basically the repository link and a warning about the https://linux-archive.web.cern.ch
    • You may need to update our custom CSS in docs/stylesheets/extra.css, normally class names or certain sizes.
• Do what you just did to https://gitlab.cern.ch/linuxsupport/websites/linux-archive.web.cern.ch

To deploy the new MkDocs image, go to your Openshift project -> Builds -> linux-docs -> Edit -> Change the image stream version to the desired one.

Note that if this is no longer maintained we may need to use a fork of it and maintain our own versions, Image Streams and so on.