From 4ff026d3ed092ef3fe7612ca7e201c68d84f524f Mon Sep 17 00:00:00 2001
From: Rik Huijzer <rikh@noreply.codeberg.org>
Date: Sat, 9 Mar 2024 03:50:55 +0000
Subject: [PATCH] admin: add a Docker Compose runner example (#474)

This PR extends the examples that were provided by @earl-warren in https://codeberg.org/forgejo/runner. I've tested this configuration twice today on two completely separate servers. For more information about the whole process that I've used, see https://huijzer.xyz/posts/forgejo-setup/.

I'll try to extract upstream a bit more information to the Forgejo docs. Feel free to take anything from my blog that seems useful and don't worry about credits. Feel free to copy whatever seems useful.

Co-authored-by: Rik Huijzer <github@huijzer.xyz>
Reviewed-on: https://codeberg.org/forgejo/docs/pulls/474
Reviewed-by: Earl Warren <earl-warren@noreply.codeberg.org>
Co-authored-by: Rik Huijzer <rikh@noreply.codeberg.org>
Co-committed-by: Rik Huijzer <rikh@noreply.codeberg.org>
---
 docs/admin/actions.md | 76 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 75 insertions(+), 1 deletion(-)

diff --git a/docs/admin/actions.md b/docs/admin/actions.md
index fd64468b..a952225e 100644
--- a/docs/admin/actions.md
+++ b/docs/admin/actions.md
@@ -122,7 +122,81 @@ $ docker run --rm code.forgejo.org/forgejo/runner:3.3.0 id
 uid=1000 gid=1000 groups=1000
 ```
 
-A [docker-compose](https://docs.docker.com/compose/) example [is
+One way to run the Docker image is via Docker Compose. To do so,
+first prepare a `data` directory with non-root permissions
+(in this case, we pick `1001:1001`):
+
+```shell
+#!/usr/bin/env bash
+
+set -e
+
+mkdir -p data
+touch data/.runner
+mkdir -p data/.cache
+
+chown -R 1001:1001 data/.runner
+chown -R 1001:1001 data/.cache
+chmod 775 data/.runner
+chmod 775 data/.cache
+chmod g+s data/.runner
+chmod g+s data/.cache
+```
+
+After running this script with `bash setup.sh`, define the following
+`docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  docker-in-docker:
+    image: docker:dind
+    container_name: 'docker_dind'
+    privileged: true
+    command: ['dockerd', '-H', 'tcp://0.0.0.0:2375', '--tls=false']
+    restart: 'unless-stopped'
+
+  gitea:
+    image: 'code.forgejo.org/forgejo/runner:3.3.0'
+    links:
+      - docker-in-docker
+    depends_on:
+      docker-in-docker:
+        condition: service_started
+    container_name: 'runner'
+    environment:
+      DOCKER_HOST: tcp://docker-in-docker:2375
+    # User without root privileges, but with access to `./data`.
+    user: 1001:1001
+    volumes:
+      - ./data:/data
+    restart: 'unless-stopped'
+
+    command: '/bin/sh -c "while : ; do sleep 1 ; done ;"'
+```
+
+Here, we're not running the `forgejo-runner daemon` yet because we
+need to register it first. Follow the registration instructions below
+by starting the `runner` service with `docker-compose up -d` and
+entering it via:
+
+```shell
+docker exec -it runner /bin/sh
+```
+
+In this shell, run the `forgejo-runner register` command as described
+below. After that is done, take the service down again with
+`docker-compose down` and modify the `command` to:
+
+```yaml
+command: '/bin/sh -c "sleep 5; forgejo-runner daemon"'
+```
+
+Here, the sleep allows the `docker-in-docker` service to start up
+before the `forgejo-runner daemon` is started.
+
+More [docker compose](https://docs.docker.com/compose/) examples [are
 provided](https://codeberg.org/forgejo/runner/src/branch/main/examples/docker-compose)
 to demonstrate how to install that OCI image to successfully run a workflow.