# 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/).