gitcaddy/GitCaddy Runner
Limited
2
0
Fork 0
Code Issues Releases 5

docs(detached-note): add runner user guide and update deployment examples

Browse Source 
Add comprehensive GUIDE.md (1000+ lines) covering GitCaddy Runner installation, registration, configuration, deployment options (Docker, Kubernetes, VM), workflow examples, artifact handling, cache server setup, and troubleshooting.

Update all deployment example READMEs with improved instructions and clarifications for Docker Compose, Kubernetes (DinD and rootless), and VM deployments. Enhance YAML configurations with better comments and security practices.
This commit is contained in:
David H. Friedel Jr.
2026-01-27 22:50:23 -05:00
parent d388ec5519
commit 259238eedf
9 changed files with 1100 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1039
GUIDE.md Normal file
View File

File diff suppressed because it is too large Load Diff

14
examples/README.md
View File

@@ -1,12 +1,12 @@
# Usage Examples for `act_runner`
# Usage Examples for `gitcaddy-runner`
Welcome to our collection of usage and deployment examples specifically designed for Gitea setups. Whether you're a beginner or an experienced user, you'll find practical resources here that you can directly apply to enhance your Gitea experience. We encourage you to contribute your own insights and knowledge to make this collection even more comprehensive and valuable.
A collection of usage and deployment examples for GitCaddy Runner. Whether you're a beginner or an experienced user, you'll find practical resources here that you can directly apply to your GitCaddy setup. We encourage you to contribute your own insights and knowledge to make this collection even more comprehensive and valuable.
| Section | Description |
|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`docker`](docker) | This section provides you with scripts and instructions tailored for running containers on a workstation or server where Docker is installed. It simplifies the process of setting up and managing your Gitea deployment using Docker. |
| [`docker-compose`](docker-compose) | In this section, you'll discover examples demonstrating how to utilize docker-compose to efficiently handle your Gitea deployments. It offers a straightforward approach to managing multiple containerized components of your Gitea setup. |
| [`kubernetes`](kubernetes) | If you're utilizing Kubernetes clusters for your infrastructure, this section is specifically designed for you. It presents examples and guidelines for configuring Gitea deployments within Kubernetes clusters, enabling you to leverage the scalability and flexibility of Kubernetes. |
| [`vm`](vm) | This section is dedicated to examples that assist you in setting up Gitea on virtual or physical servers. Whether you're working with virtual machines or physical hardware, you'll find helpful resources to guide you through the deployment process. |
| [`docker`](docker) | Scripts and instructions for running GitCaddy Runner in a Docker container on a workstation or server where Docker is installed. |
| [`docker-compose`](docker-compose) | Examples demonstrating how to use docker-compose to run GitCaddy Runner alongside a GitCaddy server instance. |
| [`kubernetes`](kubernetes) | Examples and guidelines for deploying GitCaddy Runner within Kubernetes clusters, leveraging scalability and flexibility. |
| [`vm`](vm) | Examples for setting up GitCaddy Runner on virtual or physical servers directly, without containerization. |
We hope these resources provide you with valuable insights and solutions for your Gitea setup. Feel free to explore, contribute, and adapt these examples to suit your specific requirements.
Feel free to explore, contribute, and adapt these examples to suit your specific requirements.

25
examples/docker-compose/README.md
View File

@@ -1,12 +1,12 @@
### Running `act_runner` using `docker-compose`
### Running `gitcaddy-runner` using `docker-compose`
```yml
...
gitea:
image: gitea/gitea
gitcaddy:
image: git.marketally.com/gitcaddy/server:latest
...
healthcheck:
# checks availability of Gitea's front-end with curl
# checks availability of GitCaddy's front-end with curl
test: ["CMD", "curl", "-f", "<instance_url>"]
interval: 10s
retries: 3
@@ -14,20 +14,19 @@
timeout: 10s
environment:
# GITEA_RUNNER_REGISTRATION_TOKEN can be used to set a global runner registration token.
# The Gitea version must be v1.23 or higher.
# It's also possible to use GITEA_RUNNER_REGISTRATION_TOKEN_FILE to pass the location.
# - GITEA_RUNNER_REGISTRATION_TOKEN=<user-defined registration token>
runner:
image: gitea/act_runner
image: git.marketally.com/gitcaddy/gitcaddy-runner:latest
restart: always
depends_on:
gitea:
# required so runner can attach to gitea, see "healthcheck"
gitcaddy:
# required so runner can attach to GitCaddy, see "healthcheck"
condition: service_healthy
restart: true
volumes:
- ./data/act_runner:/data
- ./data/gitcaddy-runner:/data
- /var/run/docker.sock:/var/run/docker.sock
environment:
- GITEA_INSTANCE_URL=<instance url>
@@ -38,18 +37,18 @@
- GITEA_RUNNER_REGISTRATION_TOKEN=<registration token>
```
### Running `act_runner` using Docker-in-Docker (DIND)
### Running `gitcaddy-runner` using Docker-in-Docker (DIND)
```yml
...
runner:
image: gitea/act_runner:latest-dind-rootless
image: git.marketally.com/gitcaddy/gitcaddy-runner:latest-dind-rootless
restart: always
privileged: true
depends_on:
- gitea
- gitcaddy
volumes:
- ./data/act_runner:/data
- ./data/gitcaddy-runner:/data
environment:
- GITEA_INSTANCE_URL=<instance url>
- DOCKER_HOST=unix:///var/run/user/1000/docker.sock

4
examples/docker/README.md
View File

@@ -1,7 +1,7 @@
### Run `act_runner` in a Docker Container
### Run `gitcaddy-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
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 git.marketally.com/gitcaddy/gitcaddy-runner:latest
```
The `/data` directory inside the docker container contains the runner API keys after registration.

2
examples/kubernetes/README.md
View File

@@ -1,4 +1,4 @@
## Kubernetes Docker in Docker Deployment with `act_runner`
## Kubernetes Docker in Docker Deployment with `gitcaddy-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.

18
examples/kubernetes/dind-docker.yaml
View File

@@ -1,7 +1,7 @@
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
name: act-runner-vol
name: gitcaddy-runner-vol
spec:
accessModes:
- ReadWriteOnce
@@ -13,7 +13,7 @@ spec:
apiVersion: v1
data:
# The registration token can be obtained from the web UI, API or command-line.
# You can also set a pre-defined global runner registration token for the Gitea instance via
# You can also set a pre-defined global runner registration token for the GitCaddy instance via
# `GITEA_RUNNER_REGISTRATION_TOKEN`/`GITEA_RUNNER_REGISTRATION_TOKEN_FILE` environment variable.
token: << base64 encoded registration token >>
kind: Secret
@@ -25,19 +25,19 @@ apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: act-runner
name: act-runner
app: gitcaddy-runner
name: gitcaddy-runner
spec:
replicas: 1
selector:
matchLabels:
app: act-runner
app: gitcaddy-runner
strategy: {}
template:
metadata:
creationTimestamp: null
labels:
app: act-runner
app: gitcaddy-runner
spec:
restartPolicy: Always
volumes:
@@ -45,10 +45,10 @@ spec:
emptyDir: {}
- name: runner-data
persistentVolumeClaim:
claimName: act-runner-vol
claimName: gitcaddy-runner-vol
containers:
- name: runner
image: gitea/act_runner:nightly
image: git.marketally.com/gitcaddy/gitcaddy-runner:latest
command: ["sh", "-c", "while ! nc -z localhost 2376 </dev/null; do echo 'waiting for docker daemon...'; sleep 5; done; /sbin/tini -- run.sh"]
env:
- name: DOCKER_HOST
@@ -58,7 +58,7 @@ spec:
- name: DOCKER_TLS_VERIFY
value: "1"
- name: GITEA_INSTANCE_URL
value: http://gitea-http.gitea.svc.cluster.local:3000
value: http://gitcaddy-http.gitcaddy.svc.cluster.local:3000
- name: GITEA_RUNNER_REGISTRATION_TOKEN
valueFrom:
secretKeyRef:

19
examples/kubernetes/rootless-docker.yaml
View File

@@ -1,7 +1,7 @@
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
name: act-runner-vol
name: gitcaddy-runner-vol
spec:
accessModes:
- ReadWriteOnce
@@ -13,7 +13,7 @@ spec:
apiVersion: v1
data:
# The registration token can be obtained from the web UI, API or command-line.
# You can also set a pre-defined global runner registration token for the Gitea instance via
# You can also set a pre-defined global runner registration token for the GitCaddy instance via
# `GITEA_RUNNER_REGISTRATION_TOKEN`/`GITEA_RUNNER_REGISTRATION_TOKEN_FILE` environment variable.
token: << base64 encoded registration token >>
kind: Secret
@@ -25,30 +25,30 @@ apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: act-runner
name: act-runner
app: gitcaddy-runner
name: gitcaddy-runner
spec:
replicas: 1
selector:
matchLabels:
app: act-runner
app: gitcaddy-runner
strategy: {}
template:
metadata:
creationTimestamp: null
labels:
app: act-runner
app: gitcaddy-runner
spec:
restartPolicy: Always
volumes:
- name: runner-data
persistentVolumeClaim:
claimName: act-runner-vol
claimName: gitcaddy-runner-vol
securityContext:
fsGroup: 1000
containers:
- name: runner
image: gitea/act_runner:nightly-dind-rootless
image: git.marketally.com/gitcaddy/gitcaddy-runner:latest-dind-rootless
imagePullPolicy: Always
# 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:
@@ -59,7 +59,7 @@ spec:
- name: DOCKER_TLS_VERIFY
value: "1"
- name: GITEA_INSTANCE_URL
value: http://gitea-http.gitea.svc.cluster.local:3000
value: http://gitcaddy-http.gitcaddy.svc.cluster.local:3000
- name: GITEA_RUNNER_REGISTRATION_TOKEN
valueFrom:
secretKeyRef:
@@ -70,4 +70,3 @@ spec:
volumeMounts:
- name: runner-data
mountPath: /data

2
examples/vm/README.md
View File

@@ -1,4 +1,4 @@
## `act_runner` on Virtual or Physical Servers
## `gitcaddy-runner` on Virtual or Physical Servers
Files in this directory:

37
examples/vm/rootless-docker.md
View File

@@ -1,12 +1,12 @@
## Using Rootless Docker with`act_runner`
## Using Rootless Docker with `gitcaddy-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.
Here is a simple example of how to set up `gitcaddy-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`.
- Create a user to run both `docker` and `gitcaddy-runner`. In this example, we use a non-privileged account called `rootless`.
```bash
useradd -m rootless
@@ -38,36 +38,36 @@ export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock
```
- Reboot. Ensure that the Docker process is working.
- Create a directory for saving `act_runner` data between restarts
- Create a directory for saving `gitcaddy-runner` data between restarts
`mkdir /home/rootless/act_runner`
`mkdir /home/rootless/gitcaddy-runner`
- Register the runner from the data directory
```bash
cd /home/rootless/act_runner
act_runner register
cd /home/rootless/gitcaddy-runner
gitcaddy-runner register
```
- Generate a `act_runner` configuration file in the data directory. Edit the file to adjust for the system.
- Generate a `gitcaddy-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
gitcaddy-runner generate-config >/home/rootless/gitcaddy-runner/config
```
- Create a new user-level`systemd` unit file as `/home/rootless/.config/systemd/user/act_runner.service` with the following contents:
- Create a new user-level `systemd` unit file as `/home/rootless/.config/systemd/user/gitcaddy-runner.service` with the following contents:
```bash
Description=Gitea Actions runner
Documentation=https://gitea.com/gitea/act_runner
Description=GitCaddy Actions runner
Documentation=https://git.marketally.com/gitcaddy/gitcaddy-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
ExecStart=/usr/bin/gitcaddy-runner daemon -c /home/rootless/gitcaddy-runner/config
ExecReload=/bin/kill -s HUP $MAINPID
WorkingDirectory=/home/rootless/act_runner
WorkingDirectory=/home/rootless/gitcaddy-runner
TimeoutSec=0
RestartSec=2
Restart=always
@@ -88,8 +88,9 @@ export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock
- Reboot
After the system restarts, check that the`act_runner` is working and that the runner is connected to Gitea.
After the system restarts, check that `gitcaddy-runner` is working and that the runner is connected to GitCaddy.
````bash
systemctl --user status act_runner
journalctl --user -xeu act_runner
```bash
systemctl --user status gitcaddy-runner
journalctl --user -xeu gitcaddy-runner
```