Gitea Runner Proxmox LXC setup script following community-scripts conventions

README.md

@@ -0,0 +1,158 @@
+# Gitea Runner Proxmox LXC Script
+
+A script to deploy an official **Gitea Actions Runner** in an unprivileged Proxmox VE LXC container with **Docker CE** pre-installed and configured, styled and structured following [Community Scripts (Proxmox VE Helper-Scripts)](https://community-scripts.org/).
+
+```text
+   _______ __                   ____                               
+  / ____(_) /____  ____ _      / __ \__  ______  ____  ___  _____  
+ / / __/ / __/ _ \/ __ `/_____/ /_/ / / / / __ \/ __ \/ _ \/ ___/  
+/ /_/ / / /_/  __/ /_/ /_____/ _, _/ /_/ / / / / / / /  __/ /      
+\____/_/\__/\___/\__,_/     /_/ |_|\__,_/_/ /_/_/ /_/\___/_/       
+```
+
+---
+
+## ⚡ Quick Start
+
+Run the following command directly in your **Proxmox VE Shell**:
+
+```bash
+bash -c "$(curl -fsSL https://git.mattway.com.au/matt/gitea-runner-script/raw/branch/main/ct/gitea-runner.sh)"
+```
+
+*(Optional: You can also clone and run locally on the Proxmox host)*
+```bash
+git clone https://git.mattway.com.au/matt/gitea-runner-script.git
+./gitea-runner-script/ct/gitea-runner.sh
+```
+
+---
+
+## ⚙️ Container Default Specifications
+
+| Setting | Default Value | Notes |
+| :--- | :--- | :--- |
+| **OS** | Debian 12 / 13 | Alpine is also selectable during setup |
+| **CPU** | 2 vCPU | Suitable for concurrent CI tasks and compilation |
+| **RAM** | 2048 MB | Sufficient for Docker engine and CI workloads |
+| **Disk** | 15 GB | Provides headroom for caching Docker layers |
+| **Type** | Unprivileged (`1`) | Enhanced container isolation |
+| **Features** | `nesting=1`, `keyctl=1` | Required for running Docker inside an unprivileged LXC |
+
+---
+
+## 🔑 Registering with your Gitea Instance
+
+### 1. Obtain a Registration Token from Gitea
+You can register the runner at the instance level, organization level, or repository level:
+* **Instance-wide**: *Site Administration* → *Actions* → *Runners* → **Create new Runner**
+* **Organization-level**: *Organization Settings* → *Actions* → *Runners* → **Create new Runner**
+* **Repository-level**: *Repository Settings* → *Actions* → *Runners* → **Create new Runner**
+
+Copy the generated **Registration Token**.
+
+---
+
+### 2. Connect the Runner
+
+You can register the runner interactively during installation, or anytime afterwards:
+
+#### Option A: From Proxmox VE Host Shell
+```bash
+pct exec <CTID> -- gitea-runner-register
+```
+
+#### Option B: From Inside Container Console
+```bash
+gitea-runner-register
+```
+
+#### Option C: Non-interactive / Headless Registration
+```bash
+pct exec <CTID> -- gitea-runner-register \
+  --instance "https://git.mattway.com.au" \
+  --token "<YOUR_REGISTRATION_TOKEN>" \
+  --name "pve-runner-01" \
+  --labels "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest,ubuntu-22.04:docker://docker.gitea.com/runner-images:ubuntu-22.04,ubuntu-24.04:docker://docker.gitea.com/runner-images:ubuntu-24.04"
+```
+
+Once registered, the helper starts and enables the `gitea-runner.service` systemd daemon. The runner will immediately show as **Idle** (green) in your Gitea web interface!
+
+---
+
+## 🛠️ Configuration & Service Management
+
+* **Configuration file**: `/etc/gitea-runner/config.yaml` (symlinked from `/etc/act_runner/config.yaml`)
+* **State file**: `/etc/gitea-runner/.runner`
+* **Systemd Service**: `gitea-runner.service` (alias `act_runner.service`)
+
+### Common Management Commands (Inside Container)
+
+* **Check service status**:
+  ```bash
+  systemctl status gitea-runner
+  ```
+* **View live logs**:
+  ```bash
+  journalctl -u gitea-runner -f
+  ```
+* **Restart runner daemon**:
+  ```bash
+  systemctl restart gitea-runner
+  ```
+* **Verify Docker**:
+  ```bash
+  docker info
+  ```
+
+---
+
+## 🔄 Updating the Runner
+
+Just like other containers created with Community Scripts, you can update this container at any time by simply running the built-in `update` command:
+
+### Option A: From inside the container console
+```bash
+update
+```
+
+### Option B: From the Proxmox VE host shell
+```bash
+pct exec <CTID> -- update
+```
+
+### Option C: Via curl one-liner
+```bash
+bash -c "$(curl -fsSL https://git.mattway.com.au/matt/gitea-runner-script/raw/branch/main/ct/gitea-runner.sh)"
+```
+
+When executed, the update process automatically:
+1. Runs safe APT OS updates (`apt-get update && apt-get upgrade -y`).
+2. Checks for Docker engine updates.
+3. Checks for the latest release on the official Gitea repository.
+4. Stops the service, safely updates the binary, and restarts the daemon if a new version is detected.
+
+---
+
+## 📁 Repository Structure
+
+Built following the official Community Scripts architecture:
+
+```text
+├── ct/
+│   ├── gitea-runner.sh          # Proxmox host creation and update script
+│   └── headers/
+│       └── gitea-runner         # ASCII art banner
+├── install/
+│   └── gitea-runner-install.sh  # In-container provisioning script
+├── gitea-runner.sh              # Root launcher entrypoint
+├── LICENSE                      # MIT License
+└── README.md                    # Documentation
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).
+Built with the foundation and conventions established by [community-scripts ORG](https://community-scripts.org/).