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>
This commit is contained in:
parent
e3271d8469
commit
a384adbbc6
8 changed files with 225 additions and 28 deletions
30
README.md
30
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
|
./act_runner -c config.yaml daemon # run with config file
|
||||||
```
|
```
|
||||||
|
|
||||||
### Run a docker container
|
### Example Deployments
|
||||||
|
|
||||||
```sh
|
Check out the [examples](examples) directory for sample deployment types.
|
||||||
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>
|
|
||||||
```
|
|
||||||
|
|
16
examples/README.md
Normal file
16
examples/README.md
Normal file
|
@ -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.
|
20
examples/docker-compose/README.md
Normal file
20
examples/docker-compose/README.md
Normal file
|
@ -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>
|
||||||
|
```
|
8
examples/docker/README.md
Normal file
8
examples/docker/README.md
Normal file
|
@ -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.
|
8
examples/kubernetes/README.md
Normal file
8
examples/kubernetes/README.md
Normal file
|
@ -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.
|
78
examples/kubernetes/dind-docker.yaml
Normal file
78
examples/kubernetes/dind-docker.yaml
Normal file
|
@ -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
|
6
examples/vm/README.md
Normal file
6
examples/vm/README.md
Normal file
|
@ -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.
|
87
examples/vm/rootless-docker.md
Normal file
87
examples/vm/rootless-docker.md
Normal file
|
@ -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
|
Loading…
Reference in a new issue