### New infrastructure for documentation sites (based on Gitlab Pages) --- #### Why did we decide to change the architecture? - creation of new sites required many manual steps to be performed and it wasn't very friendly for less technical users - hidden steps in between (S2I container image whose responsibility was to build the static assets) made the whole setup harder to understand (in case someone wanted to customize the builds) --- #### More reasons for the change - necessity to streamline the architecture based on the components we commonly use - imminent decommissioning campaign of Openshift 3 made us rethink the solution used so far - future integration with the new WebServices Portal --- #### What changed --- #### Gitlab CI is now responsible for building static assets Static assets are no longer built on Openshift. Now Gitlab CI/CD is responsible for that  In order to build your MkDocs site you can use our [Gitlab CI/CD template](https://gitlab.cern.ch/authoring/documentation/mkdocs-ci/). --- #### Integration with the new Keycloak-based SSO Now you can protect your static sites with new Keycloak-based SSO.  --- #### MkDocs is not the only option now Users can now use other Static Site Generators offered by Gitlab Pages as well as MkDocs.  There is also one interesting option which is a WYSIWYG editor that can prove to be useful to users who don't want to learn Markdown. --- #### Based on OKD4 (webeos.cern.ch) All the components of the new infrastructure are deployed on an OKD4 cluster ([webeos.cern.ch](https://webeos.cern.ch)). All of them are regularly updated and have been designed in a way that will streamline the future integration with the new `WebServices Portal`. --- #### `nginx` not needed for setting up redirects Thanks to [`_redirects`](https://docs.gitlab.com/ee/user/project/pages/redirects.html) file, which is supported by Gitlab Pages, there is no need to use `nginx` for custom redirections. ``` /home / 302 /home-not-existing / 302 # should be soon available /news/* /blog/:splat /news/:year/:month/:date /blog-:year-:month-:date.html ``` Keep in mind that not all types of redirects are available at the moment, e.g. domain-level redirects (however Gitlab adds support for more and more with each release) --- #### Review sites Due to a limitation in how static site content is stored by `Gitlab`, reviewing a site requires a few more steps from the users. We suggest that users use a repository fork to test and review their changes. More info can be found [here](https://how-to.docs.cern.ch/gitlabpagessite/review/create_test_site/). The suggested workaround above might be replaced with [Review Apps for Pages](https://gitlab.com/gitlab-org/gitlab/-/issues/16907) once it is fully implemented. --- #### Architecture (plain Gitlab Pages) ```mermaid flowchart TB user[Site Owner]-- Pushes pages deployment -->gitlab{Gitlab} gitlab{Gitlab}-- Pushes static content -->s3[(Object Storage)] pages((Gitlab Pages))-. Reads configuration from API .->gitlab{Gitlab} pages((Gitlab Pages))-. Reads static content .->s3[(Object Storage)] pages((Gitlab Pages))-. Serves static content .->users(Visitors) ``` --- #### Architecture (CERN customization) ```mermaid flowchart TB user[Site Owner]-- Creates resource on webeos.cern.ch -->okd[webeos.cern.ch] user[Site Owner]-- Pushes pages deployment plus creates a custom Pages domain -->gitlab{Gitlab} gitlab{Gitlab}-- Pushes static content -->s3[(Object Storage)] visitor[Visitor]-. Visits e.g. how-to.docs.cern.ch .->haproxy[Auth Proxy] operator[Custom K8S operator]-. Dynamically generates httpd config for each site .->haproxy[Auth Proxy] haproxy[Auth Proxy]-- Authenticates requests if necessary before proxying it to Gitlab Pages -->pages((Gitlab Pages)) pages((Gitlab Pages))-. Reads configuration from API .->gitlab{Gitlab} pages((Gitlab Pages))-. Stores and reads static content .->s3[(Object Storage)] ``` --- #### Alternative solution for highly-customized pages In some cases, migration to the new infrastructure can turn out to be problematic, e.g.: * if custom `nginx` configuration can't be easily converted to the [_redirects rules](https://docs.gitlab.com/ee/user/project/pages/redirects.html) * or if build assets of the site exceed `Gitlab Pages` limits In those cases, we recommend that users use our custom `Helm` chart that should be soon available to our users. --- #### Some stats As of today (29.11.2021) there are **193** sites hosted on the new infrastructure whereas there are still **126** sites left to be migrated. --- #### More info You can find more information on how to provision or migrate your site in [our documentation](https://how-to.docs.cern.ch). --- #### Demo