Merge branch 'document-ci' into 'master'

Document how the Baserock runners for GitLab CI are set up

See merge request baserock/infrastructure!9

1 files changed, 33 insertions, 22 deletions

diff --git a/README.mdwn b/README.mdwn
index 79b43592..bcbd5d40 100644
--- a/README.mdwn
+++ b/README.mdwn
@@ -468,8 +468,7 @@ of the subdomains:
     cd letsencrypt.sh
     cat >domains.txt <<'EOF'
     baserock.org
-    cache.baserock.org docs.baserock.org download.baserock.org gerrit.baserock.org irclogs.baserock.org openid.baserock.org ostree.baserock.org paste.baserock.org spec.baserock.org
-    storyboard.baserock.org
+    docs.baserock.org download.baserock.org irclogs.baserock.org ostree.baserock.org paste.baserock.org spec.baserock.org
     git.baserock.org
     EOF
 
@@ -502,29 +501,17 @@ certificates that are present in `certs` and `private` you will have to:
 
     # Create some full certs including key for some services that need it this way
     cat git.baserock.org/cert.csr git.baserock.org/cert.pem git.baserock.org/chain.pem git.baserock.org/privkey.pem > tmp/private/git-with-key.pem
-    cat cache.baserock.org/cert.csr cache.baserock.org/cert.pem cache.baserock.org/chain.pem cache.baserock.org/privkey.pem > tmp/private/frontend-with-key.pem
 
     # Copy key files
     cp git.baserock.org/privkey.pem tmp/private/git.pem
-    cp cache.baserock.org/privkey.pem tmp/private/frontend.pem
-    cp storyboard.baserock.org/privkey.pem tmp/private/storyboard.pem
-
 
     # Copy cert files
     cp git.baserock.org/cert.csr tmp/certs/git.csr
     cp git.baserock.org/cert.pem tmp/certs/git.pem
     cp git.baserock.org/chain.pem tmp/certs/git-chain.pem
-    cp cache.baserock.org/cert.csr tmp/certs/frontend.csr
-    cp cache.baserock.org/cert.pem tmp/certs/frontend.pem
-    cp cache.baserock.org/chain.pem tmp/certs/frontend-chain.pem
-    cp storyboard.baserock.org/cert.csr tmp/certs/storyboard.csr
-    cp storyboard.baserock.org/cert.pem tmp/certs/storyboard.pem
-    cp storyboard.baserock.org/chain.pem tmp/certs/storyboard-chain.pem
 
     # Create full certs without keys
     cat git.baserock.org/cert.csr git.baserock.org/cert.pem chain.pem > tmp/certs/git-full.pem
-    cat cache.baserock.org/cert.csr cache.baserock.org/cert.pem cache.baserock.org/chain.pem > tmp/certs/frontend-full.pem
-    cat storyboard.baserock.org/cert.csr storyboard.baserock.org/cert.pem storyboard.baserock.org/chain.pem > tmp/certs/storyboard-full.pem
 
 Before replacing the current ones, make sure you **encrypt** the ones that contain
 keys (located in `private` folder):
@@ -540,7 +527,6 @@ And copy them to the repo:
 Deploy certificates
 -------------------
 
-
 For `git.baserock.org` just run:
 
     ansible-playbook -i hosts baserock_trove/configure-trove.yml
@@ -548,20 +534,45 @@ For `git.baserock.org` just run:
 This script will copy the certificates to the Trove and run the scripts
 that will configure them.
 
-
 For the frontend, run:
 
     ansible-playbook -i hosts baserock_frontend/instance-config.yml
     ansible -i hosts -m service -a 'name=haproxy enabled=true state=restarted' --sudo frontend-haproxy
-    ansible-playbook -i hosts baserock_gerrit/instance-ca-certificate-config.yml
-    ansible -i hosts -m service -a 'name=gerrit enabled=true state=restarted' --sudo gerrit
 
 Which will install the certificates and then restart the services needed.
 
 
-For StoryBoard, run:
+GitLab CI runners setup
+=======================
 
-    ansible-playbook -i hosts baserock_storyboard/instance-storyboard-config.yml
+Baserock uses [GitLab CI] for build and test automation. For performance reasons
+we provide our own runners and avoid using the free, shared runners provided by
+GitLab. The runners are hosted at [DigitalOcean] and managed by the 'baserock'
+team account there.
+
+There is a persistent 'manager' machine with a public IP of 138.68.143.2 that
+runs GitLab Runner and [docker-machine]. This doesn't run any builds itself --
+we use the [autoscaling feature] of GitLab Runner to spawn new VMs for building
+in. The configuration for this is in `/etc/gitlab-runner/config.toml`.
+
+Each build occurs in a Docker container on one of the transient VMs. As per
+the [\[runners.docker\] section] of `config.toml`, each gets a newly created
+volume mounted at `/cache`. The YBD and BuildStream cache directories get
+located here because jobs were running out of disk space when using the default
+configuration.
 
-This script will trigger a full deployment. It will take a bit longer than the
-others, but will do the job.
+There is a second persistent machine with a public IP of 46.101.48.48 that
+hosts a Docker registry and a [Minio] cache. These services run as Docker
+containers. The Docker registry exists to cache the Docker images we use which
+improves the spin-up time of the transient builder VMs, as documented
+[here](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-docker-registry-mirroring).
+The Minio cache is used for the [distributed caching] feature of GitLab CI.
+
+
+[GitLab CI]: https://about.gitlab.com/features/gitlab-ci-cd/
+[DigitalOcean]: https://cloud.digitalocean.com/
+[docker-machine]: https://docs.docker.com/machine/
+[autoscaling feature]: https://docs.gitlab.com/runner/configuration/autoscale.html
+[Minio]: https://www.minio.io/
+[\[runners.docker\] section]: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-docker-section
+[distributed caching]: https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching