Merge branch 'improve-docs' into 'gesis'

Add placeholder for GESIS documentation

See merge request methods-hub/interactive-environment!19

.gitlab-ci.yml

@@ -2,13 +2,36 @@ variables:
   GIT_STRATEGY: clone
   GIT_CLEAN_FLAGS: "-ffdx"
 
+.gesis-manual-web:
+  rules:
+    - if: $CI_SERVER_HOST == 'git.gesis.org' && $CI_PIPELINE_SOURCE == 'web'
+      when: manual
+      allow_failure: true
+
+.geis-merge-request:
+  rules:
+    - if: $CI_SERVER_HOST == 'git.gesis.org' && $CI_PIPELINE_SOURCE == "merge_request_event"
+      changes:
+        - .gitlab.yml
+      when: manual  
+    - if: $CI_SERVER_HOST == 'git.gesis.org' && $CI_PIPELINE_SOURCE == "merge_request_event"
+      changes:
+        - ansible/**/*
+        - mybinder/**/*
+        - config/**/*
+        - secrets/**/*
+
+.geis-push-main:
+  rules:
+    - if: $CI_SERVER_HOST == 'git.gesis.org' && $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == 'main'
+
 stages:
   - build
   - deploy-stage-ansible
   - deploy-stage-helm
   - test-stage
-  - deploy-prod-nginx
-  - deploy-prod-helm
+  - deploy-production-ansible
+  - deploy-production-helm
 
 include:
   - component: $CI_SERVER_FQDN/rse/docker/images/ansible/ansible-lint@10.2.6
@@ -75,12 +98,31 @@ include:
 gesis helm stage deploy:
   resource_group: stage
   stage: deploy-stage-helm
+  rules:
+    - !reference [.gesis-manual-web, rules]
+    - !reference [.geis-merge-request, rules]
+    - !reference [.geis-push-main, rules]
+  variables:
+    HELM_ENVIRONMENT: stage
+  extends:
+    - .gesis helm deploy
+
+gesis helm production deploy:
+  resource_group: production
+  stage: deploy-production-helm
+  rules:
+    - !reference [.gesis-manual-web, rules]
+    - !reference [.geis-push-main, rules]
   variables:
     HELM_ENVIRONMENT: stage
   extends:
     - .gesis helm deploy
 
-smoke test to stage cluster:
+smoke test after stage deploy:
   stage: test-stage
+  rules:
+    - !reference [.gesis-manual-web, rules]
+    - !reference [.geis-merge-request, rules]
+    - !reference [.geis-push-main, rules]
   script:
     - curl https://notebooks-test.gesis.org/binder/

docs/source/deployment/gesis.md

@@ -0,0 +1,40 @@
+# How to deploy a change to notebooks.gesis.org?
+
+[GESIS Leibniz Institute for the Social Sciences](https://www.gesis.org) is a member of the [mybinder.org federation](https://mybinder.readthedocs.io/en/latest/about/status.html). GESIS has on-premise servers and use it for the mybinder.org server. The use of on-premise servers requires a separate deployment because the access to the servers using SSH requires the tunelling using a VPN.
+
+<!--
+sequenceDiagram
+    actor developer as Developer
+    participant git as GitHub
+    participant github-actions as GitHub Actions
+    participant gesis-gitlab as GESIS GitLab
+    participant gcp as Google Cloud
+    participant gesis-notebooks as notebooks.gesis.org
+
+    developer->>developer: git commit
+    developer->>git: git push
+    git->>github-actions: trigger
+    github-actions->>github-actions: validation
+    github-actions->>gcp: helm upgrade
+    git->>gesis-gitlab: trigger
+    gesis-gitlab->>gesis-gitlab: validation
+    gesis-gitlab->>gesis-notebooks: helm upgrade
+-->
+
+![Sequence diagram illustrating the deployment.](./gesis-diagram.svg)
+
+## GESIS GitLab CI/CD Server
+
+GESIS GitLab server runs [GitLab Community Edition v16.11.6](https://gitlab.com/gitlab-org/gitlab-foss/-/tags/v16.11.6) with [continuous integration (CI) and continuous delivery (CD)](https://about.gitlab.com/topics/ci-cd/) enable.
+
+The CI/CD jobs are defined in [`.gitlab-ci.yml`](https://github.com/jupyterhub/mybinder.org-deploy/tree/main/.gitlab-ci.yml).
+
+## Kubernetes on bare metal
+
+Cloud environments provide a load balancer to the Kubernetes clusters. Unfortunately, Kubernetes cluster does not includes a default implementation of a load balancer for the scenario that it is running on bare metal. Because of this, the deployment of mybinder.org to GESIS servers must include the configuration of a load balancer. We are using [MetalLB](https://metallb.universe.tf/) with [Ingress NGINX Controller](https://kubernetes.github.io/ingress-nginx/).
+
+![Sequence diagram illustrating the load balancer.](./gesis-load-balancer.drawio.svg)
+
+## Virtual Private Server configuration with Ansible
+
+We use [Ansible](https://www.ansible.com/) to automate the configuration of the virtual private server (VPS) provided by GESIS. After a successful configuration, we will have a operational Kubernetes cluster to deploy mybinder.org.

docs/source/deployment/index.rst

@@ -8,3 +8,4 @@ Deployment and Operation
    prereqs
    how
    what
+   gesis