service/ci.md

@@ -46,11 +46,53 @@ the runner.
 
 ## Registering more runners
 
-Anyone can run their own personal runner in their own infrastructure
-and register them inside a project on our GitLab instance. For this
-you need to first [install a runner](https://docs.gitlab.com/runner/install/) and [register it in
-GitLab](https://docs.gitlab.com/runner/register/). But we already have shared runners, if they are not
-sufficient, it might be best to request a new one from TPA.
+While we already have shared runners, in some cases it can be useful to set up a
+personal runner in your own infrastructure. This can be useful to experiment
+with a runner with a specialized configuration, or to supplement the capacity of
+TPA's shared runners.
+
+Setting up a personal runner is fairly easy. Gitlab's runners poll the
+gitlab instance rather than vice versa, so there is generally no need to deal
+with firewall rules, NAT traversal, etc. The runner will only run jobs for your
+project. In general, a personal runner set up on your development machine can
+work well.
+
+For this you need to first [install a
+runner](https://docs.gitlab.com/runner/install/) and [register it in
+GitLab](https://docs.gitlab.com/runner/register/).
+
+You will probably want to configure your runner to use a [Docker
+executor](https://docs.gitlab.com/runner/executors/docker.html), which is what
+TPA's runners are. For this you will also need to install [Docker
+engine](https://docs.docker.com/engine/install/).
+
+Example (after installing gitlab-runner and docker):
+
+```
+# Get your project's registration token. See
+# https://docs.gitlab.com/runner/register/
+REGISTRATION_TOKEN="mytoken"
+
+# Get the tags that your project uses for their jobs.
+# Generally you can get these by inspecting `.gitlab-ci.yml`
+# or inspecting past jobs in the gitlab UI.
+# See also
+# https://gitlab.torproject.org/tpo/tpa/team/-/wikis/service/ci#runner-tags
+TAG_LIST="amd64"
+
+# Example runner setup with a basic configuration.
+# See `gitlab-runner register --help` for more options.
+sudo gitlab-runner register \
+  --non-interactive \
+  --url=https://gitlab.torproject.org/ \
+  --registration-token="$REGISTRATION_TOKEN" \
+  --executor=docker \
+  --tag-list="$TAG_LIST" \
+  --docker-image=ubuntu:latest
+
+# Start the runner
+sudo service gitlab-runner start
+```
 
 ## Converting a Jenkins job