Documentation enhancements (#207)

This PR addresses the issue listed in issue #170 regarding how to set up rootless Docker. It also expands on the documentation to show how to create deployments for different environments. Co-authored-by: ccureau <ccureau@noreply.gitea.io> Reviewed-on: https://gitea.com/gitea/act_runner/pulls/207 Reviewed-by: Jason Song <i@wolfogre.com> Co-authored-by: Chris Cureau <cmcureau@gmail.com> Co-committed-by: Chris Cureau <cmcureau@gmail.com>
2023-06-05 08:46:15 +00:00 · 2023-06-05 08:46:15 +00:00 · a384adbbc6
commit a384adbbc6
parent e3271d8469
8 changed files with 225 additions and 28 deletions
--- a/README.md
+++ b/README.md
@ -88,32 +88,6 @@ You can specify the configuration file path with `-c`/`--config` argument.
 ./act_runner -c config.yaml daemon # run with config file
 ```

-### Run a docker container
+### Example Deployments

-```sh
-docker run -e GITEA_INSTANCE_URL=http://192.168.8.18:3000 -e GITEA_RUNNER_REGISTRATION_TOKEN=<runner_token> -v /var/run/docker.sock:/var/run/docker.sock -v $PWD/data:/data --name my_runner gitea/act_runner:nightly
-```
-
-The `/data` directory inside the docker container contains the runner API keys after registration.
-It must be persisted, otherwise the runner would try to register again, using the same, now defunct registration token.
-
-### Running in docker-compose
-
-```yml
-...
-  gitea:
-    image: gitea/gitea
-    ...
-
-  runner:
-    image: gitea/act_runner
-    restart: always
-    depends_on:
-      - gitea
-    volumes:
-      - ./data/act_runner:/data
-      - /var/run/docker.sock:/var/run/docker.sock
-    environment:
-      - GITEA_INSTANCE_URL=<instance url>
-      - GITEA_RUNNER_REGISTRATION_TOKEN=<registration token>
-```
+Check out the [examples](examples) directory for sample deployment types.
--- a/examples/README.md
+++ b/examples/README.md
@ -0,0 +1,16 @@
+## Usage Examples for `act_runner`
+
+Here you will find usage and deployment examples that can be directly used in a Gitea setup. Please feel free to contribute!
+
+
+- [`docker`](docker)
+  Contains scripts and instructions for running containers on a workstation or server with Docker installed.
+
+- [`docker-compose`](docker-compose)
+  Contains examples of using `docker-compose` to manage deployments.
+
+- [`kubernetes`](kubernetes)
+  Contains examples of setting up deployments in Kubernetes clusters.
+
+- [`vm`](vm)
+  Contains examples for setting up virtual or physical servers.
--- a/examples/docker-compose/README.md
+++ b/examples/docker-compose/README.md
@ -0,0 +1,20 @@
+### Running `act_runner` using `docker-compose`
+
+```yml
+...
+  gitea:
+    image: gitea/gitea
+    ...
+
+  runner:
+    image: gitea/act_runner
+    restart: always
+    depends_on:
+      - gitea
+    volumes:
+      - ./data/act_runner:/data
+      - /var/run/docker.sock:/var/run/docker.sock
+    environment:
+      - GITEA_INSTANCE_URL=<instance url>
+      - GITEA_RUNNER_REGISTRATION_TOKEN=<registration token>
+```
--- a/examples/docker/README.md
+++ b/examples/docker/README.md
@ -0,0 +1,8 @@
+### Run `act_runner` in a Docker Container
+
+```sh
+docker run -e GITEA_INSTANCE_URL=http://192.168.8.18:3000 -e GITEA_RUNNER_REGISTRATION_TOKEN=<runner_token> -v /var/run/docker.sock:/var/run/docker.sock -v $PWD/data:/data --name my_runner gitea/act_runner:nightly
+```
+
+The `/data` directory inside the docker container contains the runner API keys after registration.
+It must be persisted, otherwise the runner would try to register again, using the same, now defunct registration token.
--- a/examples/kubernetes/README.md
+++ b/examples/kubernetes/README.md
@ -0,0 +1,8 @@
+## Kubernetes Docker in Docker Deployment with `act_runner`
+
+NOTE: Docker in Docker (dind) requires elevated privileges on Kubernetes. The current way to achieve this is to set the pod `SecurityContext` to `privileged`. Keep in mind that this is a potential security issue that has the potential for a malicious application to break out of the container context.
+
+Files in this directory:
+
+- [`dind-docker.yaml`](dind-docker.yaml)
+  How to create a Deployment and Persistent Volume for Kubernetes to act as a runner. The Docker credentials are re-generated each time the pod connects and does not need to be persisted.
--- a/examples/kubernetes/dind-docker.yaml
+++ b/examples/kubernetes/dind-docker.yaml
@ -0,0 +1,78 @@
+kind: PersistentVolumeClaim
+apiVersion: v1
+metadata:
+  name: act-runner-vol
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 1Gi
+  storageClassName: standard
+---
+apiVersion: v1
+data:
+  token: << base64 encoded registration token >>
+kind: Secret
+metadata:
+  name: runner-secret
+type: Opaque
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  labels:
+    app: act-runner
+  name: act-runner
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: act-runner
+  strategy: {}
+  template:
+    metadata:
+      creationTimestamp: null
+      labels:
+        app: act-runner
+    spec:
+      restartPolicy: Always
+      volumes:
+      - name: docker-certs
+        emptyDir: {}
+      - name: runner-data
+        persistentVolumeClaim:
+          claimName: act-runner-vol
+      containers:
+      - name: runner
+        image: gitea/act_runner:nightly
+        command: ["sh", "-c", "while ! nc -z localhost 2376 </dev/null; do echo 'waiting for docker daemon...'; sleep 5; done; /sbin/tini -- /opt/act/run.sh"]
+        env:
+        - name: DOCKER_HOST
+          value: tcp://localhost:2376
+        - name: DOCKER_CERT_PATH
+          value: /certs/client
+        - name: DOCKER_TLS_VERIFY
+          value: "1"
+        - name: GITEA_INSTANCE_URL
+          value: http://gitea-http.gitea.svc.cluster.local:3000
+        - name: GITEA_RUNNER_REGISTRATION_TOKEN
+          valueFrom:
+            secretKeyRef:
+              name: runner-secret
+              key: token
+        volumeMounts:
+        - name: docker-certs
+          mountPath: /certs
+        - name: runner-data
+          mountPath: /data
+      - name: daemon
+        image: docker:23.0.6-dind
+        env:
+        - name: DOCKER_TLS_CERTDIR
+          value: /certs
+        securityContext:
+          privileged: true
+        volumeMounts:
+        - name: docker-certs
+          mountPath: /certs
--- a/examples/vm/README.md
+++ b/examples/vm/README.md
@ -0,0 +1,6 @@
+## `act_runner` on Virtual or Physical Servers
+
+Files in this directory:
+
+- [`rootless-docker.md`](rootless-docker.md)
+  How to set up a rootless docker implementation of the runner.
--- a/examples/vm/rootless-docker.md
+++ b/examples/vm/rootless-docker.md
@ -0,0 +1,87 @@
+## Using Rootless Docker with`act_runner`
+
+Here is a simple example of how to set up `act_runner` with rootless Docker. It has been created with Debian, but other Linux should work the same way.
+
+Note: This procedure needs a real login shell -- using `sudo su` or other method of accessing the account will fail some of the steps below.
+
+As `root`:
+
+- Create a user to run both `docker` and `act_runner`. In this example, we use a non-privileged account called `rootless`.
+
+```bash
+ useradd -m rootless
+ passwd rootless
+```
+
+- Install [`docker-ce`](https://docs.docker.com/engine/install/)
+- (Recommended) Disable the system-wide Docker daemon
+
+     ``systemctl disable --now docker.service docker.socket``
+
+As the `rootless` user:
+
+- Follow the instructions for [enabling rootless mode](https://docs.docker.com/engine/security/rootless/)
+- Add the following lines to the `/home/rootless/.bashrc`:
+
+```bash
+ export XDG_RUNTIME_DIR=/home/rootless/.docker/run
+ export PATH=/home/rootless/bin:$PATH
+ export DOCKER_HOST=unix:///run/user/1001/docker.sock
+```
+
+- Reboot. Ensure that the Docker process is working.
+- Create a directory for saving `act_runner` data between restarts
+
+ `mkdir /home/rootless/act_runner`
+
+- Register the runner from the data directory
+
+```bash
+ cd /home/rootless/act_runner
+ act_runner register
+```
+
+- Generate a `act_runner` configuration file in the data directory. Edit the file to adjust for the system.
+
+```bash
+ act_runner generate-config >/home/rootless/act_runner/config
+```
+
+- Create a new user-level`systemd` unit file as `/home/rootless/.config/systemd/user/act_runner.service` with the following contents:
+
+```bash
+ Description=Gitea Actions runner
+ Documentation=https://gitea.com/gitea/act_runner
+ After=docker.service
+
+ [Service]
+ Environment=PATH=/home/rootless/bin:/sbin:/usr/sbin:/home/rootless/bin:/home/rootless/bin:/home/rootless/bin:/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games
+ Environment=DOCKER_HOST=unix:///run/user/1001/docker.sock
+ ExecStart=/usr/bin/act_runner daemon -c /home/rootless/act_runner/config
+ ExecReload=/bin/kill -s HUP $MAINPID
+ WorkingDirectory=/home/rootless/act_runner
+ TimeoutSec=0
+ RestartSec=2
+ Restart=always
+ StartLimitBurst=3
+ StartLimitInterval=60s
+ LimitNOFILE=infinity
+ LimitNPROC=infinity
+ LimitCORE=infinity
+ TasksMax=infinity
+ Delegate=yes
+ Type=notify
+ NotifyAccess=all
+ KillMode=mixed
+
+ [Install]
+ WantedBy=default.target
+```
+
+- Reboot
+
+After the system restarts, check that the`act_runner` is working and that the runner is connected to Gitea.
+
+````bash
+ systemctl --user status act_runner
+ journalctl --user -xeu act_runner