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 | | 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`](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) | 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. | | [`docker-compose`](docker-compose) | Examples demonstrating how to use docker-compose to run GitCaddy Runner alongside a GitCaddy server instance. |
| [`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. | | [`kubernetes`](kubernetes) | Examples and guidelines for deploying GitCaddy Runner within Kubernetes clusters, leveraging scalability and flexibility. |
| [`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. | | [`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.

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

@@ -1,12 +1,12 @@
### Running `act_runner` using `docker-compose` ### Running `gitcaddy-runner` using `docker-compose`
```yml ```yml
... ...
gitea: gitcaddy:
image: gitea/gitea image: git.marketally.com/gitcaddy/server:latest
... ...
healthcheck: 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>"] test: ["CMD", "curl", "-f", "<instance_url>"]
interval: 10s interval: 10s
retries: 3 retries: 3
@@ -14,20 +14,19 @@
timeout: 10s timeout: 10s
environment: environment:
# GITEA_RUNNER_REGISTRATION_TOKEN can be used to set a global runner registration token. # 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. # It's also possible to use GITEA_RUNNER_REGISTRATION_TOKEN_FILE to pass the location.
# - GITEA_RUNNER_REGISTRATION_TOKEN=<user-defined registration token> # - GITEA_RUNNER_REGISTRATION_TOKEN=<user-defined registration token>
runner: runner:
image: gitea/act_runner image: git.marketally.com/gitcaddy/gitcaddy-runner:latest
restart: always restart: always
depends_on: depends_on:
gitea: gitcaddy:
# required so runner can attach to gitea, see "healthcheck" # required so runner can attach to GitCaddy, see "healthcheck"
condition: service_healthy condition: service_healthy
restart: true restart: true
volumes: volumes:
- ./data/act_runner:/data - ./data/gitcaddy-runner:/data
- /var/run/docker.sock:/var/run/docker.sock - /var/run/docker.sock:/var/run/docker.sock
environment: environment:
- GITEA_INSTANCE_URL=<instance url> - GITEA_INSTANCE_URL=<instance url>
@@ -38,18 +37,18 @@
- GITEA_RUNNER_REGISTRATION_TOKEN=<registration token> - GITEA_RUNNER_REGISTRATION_TOKEN=<registration token>
``` ```
### Running `act_runner` using Docker-in-Docker (DIND) ### Running `gitcaddy-runner` using Docker-in-Docker (DIND)
```yml ```yml
... ...
runner: runner:
image: gitea/act_runner:latest-dind-rootless image: git.marketally.com/gitcaddy/gitcaddy-runner:latest-dind-rootless
restart: always restart: always
privileged: true privileged: true
depends_on: depends_on:
- gitea - gitcaddy
volumes: volumes:
- ./data/act_runner:/data - ./data/gitcaddy-runner:/data
environment: environment:
- GITEA_INSTANCE_URL=<instance url> - GITEA_INSTANCE_URL=<instance url>
- DOCKER_HOST=unix:///var/run/user/1000/docker.sock - 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 ```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. 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. 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 kind: PersistentVolumeClaim
apiVersion: v1 apiVersion: v1
metadata: metadata:
name: act-runner-vol name: gitcaddy-runner-vol
spec: spec:
accessModes: accessModes:
- ReadWriteOnce - ReadWriteOnce
@@ -13,7 +13,7 @@ spec:
apiVersion: v1 apiVersion: v1
data: data:
# The registration token can be obtained from the web UI, API or command-line. # 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. # `GITEA_RUNNER_REGISTRATION_TOKEN`/`GITEA_RUNNER_REGISTRATION_TOKEN_FILE` environment variable.
token: << base64 encoded registration token >> token: << base64 encoded registration token >>
kind: Secret kind: Secret
@@ -25,19 +25,19 @@ apiVersion: apps/v1
kind: Deployment kind: Deployment
metadata: metadata:
labels: labels:
app: act-runner app: gitcaddy-runner
name: act-runner name: gitcaddy-runner
spec: spec:
replicas: 1 replicas: 1
selector: selector:
matchLabels: matchLabels:
app: act-runner app: gitcaddy-runner
strategy: {} strategy: {}
template: template:
metadata: metadata:
creationTimestamp: null creationTimestamp: null
labels: labels:
app: act-runner app: gitcaddy-runner
spec: spec:
restartPolicy: Always restartPolicy: Always
volumes: volumes:
@@ -45,10 +45,10 @@ spec:
emptyDir: {} emptyDir: {}
- name: runner-data - name: runner-data
persistentVolumeClaim: persistentVolumeClaim:
claimName: act-runner-vol claimName: gitcaddy-runner-vol
containers: containers:
- name: runner - 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"] command: ["sh", "-c", "while ! nc -z localhost 2376 </dev/null; do echo 'waiting for docker daemon...'; sleep 5; done; /sbin/tini -- run.sh"]
env: env:
- name: DOCKER_HOST - name: DOCKER_HOST
@@ -58,7 +58,7 @@ spec:
- name: DOCKER_TLS_VERIFY - name: DOCKER_TLS_VERIFY
value: "1" value: "1"
- name: GITEA_INSTANCE_URL - 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 - name: GITEA_RUNNER_REGISTRATION_TOKEN
valueFrom: valueFrom:
secretKeyRef: secretKeyRef:

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

@@ -1,7 +1,7 @@
kind: PersistentVolumeClaim kind: PersistentVolumeClaim
apiVersion: v1 apiVersion: v1
metadata: metadata:
name: act-runner-vol name: gitcaddy-runner-vol
spec: spec:
accessModes: accessModes:
- ReadWriteOnce - ReadWriteOnce
@@ -13,7 +13,7 @@ spec:
apiVersion: v1 apiVersion: v1
data: data:
# The registration token can be obtained from the web UI, API or command-line. # 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. # `GITEA_RUNNER_REGISTRATION_TOKEN`/`GITEA_RUNNER_REGISTRATION_TOKEN_FILE` environment variable.
token: << base64 encoded registration token >> token: << base64 encoded registration token >>
kind: Secret kind: Secret
@@ -25,30 +25,30 @@ apiVersion: apps/v1
kind: Deployment kind: Deployment
metadata: metadata:
labels: labels:
app: act-runner app: gitcaddy-runner
name: act-runner name: gitcaddy-runner
spec: spec:
replicas: 1 replicas: 1
selector: selector:
matchLabels: matchLabels:
app: act-runner app: gitcaddy-runner
strategy: {} strategy: {}
template: template:
metadata: metadata:
creationTimestamp: null creationTimestamp: null
labels: labels:
app: act-runner app: gitcaddy-runner
spec: spec:
restartPolicy: Always restartPolicy: Always
volumes: volumes:
- name: runner-data - name: runner-data
persistentVolumeClaim: persistentVolumeClaim:
claimName: act-runner-vol claimName: gitcaddy-runner-vol
securityContext: securityContext:
fsGroup: 1000 fsGroup: 1000
containers: containers:
- name: runner - name: runner
image: gitea/act_runner:nightly-dind-rootless image: git.marketally.com/gitcaddy/gitcaddy-runner:latest-dind-rootless
imagePullPolicy: Always 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"] # 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: env:
@@ -59,7 +59,7 @@ spec:
- name: DOCKER_TLS_VERIFY - name: DOCKER_TLS_VERIFY
value: "1" value: "1"
- name: GITEA_INSTANCE_URL - 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 - name: GITEA_RUNNER_REGISTRATION_TOKEN
valueFrom: valueFrom:
secretKeyRef: secretKeyRef:
@@ -70,4 +70,3 @@ spec:
volumeMounts: volumeMounts:
- name: runner-data - name: runner-data
mountPath: /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: 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. 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`: 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 ```bash
useradd -m rootless 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. - 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 - Register the runner from the data directory
```bash ```bash
cd /home/rootless/act_runner cd /home/rootless/gitcaddy-runner
act_runner register 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 ```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 ```bash
Description=Gitea Actions runner Description=GitCaddy Actions runner
Documentation=https://gitea.com/gitea/act_runner Documentation=https://git.marketally.com/gitcaddy/gitcaddy-runner
After=docker.service After=docker.service
[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=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 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 ExecReload=/bin/kill -s HUP $MAINPID
WorkingDirectory=/home/rootless/act_runner WorkingDirectory=/home/rootless/gitcaddy-runner
TimeoutSec=0 TimeoutSec=0
RestartSec=2 RestartSec=2
Restart=always Restart=always
@@ -88,8 +88,9 @@ export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock
- Reboot - 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 ```bash
systemctl --user status act_runner systemctl --user status gitcaddy-runner
journalctl --user -xeu act_runner journalctl --user -xeu gitcaddy-runner
```