From a384adbbc618be293924cc2cf650379aa148c59c Mon Sep 17 00:00:00 2001 From: Chris Cureau Date: Mon, 5 Jun 2023 08:46:15 +0000 Subject: [PATCH] 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 Reviewed-on: https://gitea.com/gitea/act_runner/pulls/207 Reviewed-by: Jason Song Co-authored-by: Chris Cureau Co-committed-by: Chris Cureau --- README.md | 30 +--------- examples/README.md | 16 +++++ examples/docker-compose/README.md | 20 +++++++ examples/docker/README.md | 8 +++ examples/kubernetes/README.md | 8 +++ examples/kubernetes/dind-docker.yaml | 78 +++++++++++++++++++++++++ examples/vm/README.md | 6 ++ examples/vm/rootless-docker.md | 87 ++++++++++++++++++++++++++++ 8 files changed, 225 insertions(+), 28 deletions(-) create mode 100644 examples/README.md create mode 100644 examples/docker-compose/README.md create mode 100644 examples/docker/README.md create mode 100644 examples/kubernetes/README.md create mode 100644 examples/kubernetes/dind-docker.yaml create mode 100644 examples/vm/README.md create mode 100644 examples/vm/rootless-docker.md diff --git a/README.md b/README.md index 9fbb75b..f031dca 100644 --- 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= -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= - - GITEA_RUNNER_REGISTRATION_TOKEN= -``` +Check out the [examples](examples) directory for sample deployment types. diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..83439c7 --- /dev/null +++ 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. diff --git a/examples/docker-compose/README.md b/examples/docker-compose/README.md new file mode 100644 index 0000000..c3b714c --- /dev/null +++ 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= + - GITEA_RUNNER_REGISTRATION_TOKEN= +``` diff --git a/examples/docker/README.md b/examples/docker/README.md new file mode 100644 index 0000000..dde2d63 --- /dev/null +++ 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= -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. diff --git a/examples/kubernetes/README.md b/examples/kubernetes/README.md new file mode 100644 index 0000000..a21d4a6 --- /dev/null +++ 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. diff --git a/examples/kubernetes/dind-docker.yaml b/examples/kubernetes/dind-docker.yaml new file mode 100644 index 0000000..98a139a --- /dev/null +++ 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 /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