From fef300dd5b9c4868781e03b740d74d4cff730ee7 Mon Sep 17 00:00:00 2001
From: GitCaddy <gitcaddy@marketally.com>
Date: Sun, 11 Jan 2026 18:18:39 +0000
Subject: [PATCH] docs: add HOWTOSTART.md guide for setting up runners
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Comprehensive guide covering:
- Prerequisites and quick start
- Registration process
- Labels configuration
- Running as a systemd service
- Docker support
- Capabilities detection
- Troubleshooting tips

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 HOWTOSTART.md | 121 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 121 insertions(+)
 create mode 100644 HOWTOSTART.md

diff --git a/HOWTOSTART.md b/HOWTOSTART.md
new file mode 100644
index 0000000..fb8ab2b
--- /dev/null
+++ b/HOWTOSTART.md
@@ -0,0 +1,121 @@
+# How to Start a GitCaddy Runner
+
+This guide explains how to set up and start a GitCaddy Actions runner (act_runner) to execute your CI/CD workflows.
+
+## Prerequisites
+
+- A Linux, macOS, or Windows machine
+- Network access to your GitCaddy/Gitea instance
+- (Optional) Docker installed for container-based workflows
+
+## Quick Start
+
+### 1. Download the Runner
+
+Download the latest release from the [releases page](https://git.marketally.com/gitcaddy/act_runner/releases) or build from source:
+
+```bash
+git clone https://git.marketally.com/gitcaddy/act_runner.git
+cd act_runner
+make build
+```
+
+### 2. Register the Runner
+
+Get a registration token from your GitCaddy instance:
+- **Global runners**: Admin Area → Actions → Runners → Create Runner
+- **Organization runners**: Organization Settings → Actions → Runners
+- **Repository runners**: Repository Settings → Actions → Runners
+
+Then register:
+
+```bash
+./act_runner register --no-interactive \
+  --instance https://your-gitea-instance.com \
+  --token YOUR_REGISTRATION_TOKEN \
+  --name my-runner \
+  --labels linux,ubuntu-latest
+```
+
+### 3. Start the Runner
+
+```bash
+./act_runner daemon
+```
+
+## Configuration Options
+
+### Runner Labels
+
+Labels determine which jobs the runner can execute. Configure labels during registration or edit them in the admin UI.
+
+Common labels:
+- `linux`, `linux-latest` - Linux runners
+- `windows`, `windows-latest` - Windows runners
+- `macos`, `macos-latest` - macOS runners
+- `ubuntu`, `ubuntu-latest` - Ubuntu-specific
+- `self-hosted` - Self-hosted runners
+
+### Running as a Service
+
+#### Linux (systemd)
+
+```bash
+sudo cat > /etc/systemd/system/act_runner.service << 'SERVICE'
+[Unit]
+Description=GitCaddy Actions Runner
+After=network.target
+
+[Service]
+Type=simple
+User=runner
+WorkingDirectory=/opt/act_runner
+ExecStart=/opt/act_runner/act_runner daemon
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+SERVICE
+
+sudo systemctl enable act_runner
+sudo systemctl start act_runner
+```
+
+### Docker Support
+
+For workflows that use container actions, ensure Docker is installed and the runner user has access:
+
+```bash
+sudo usermod -aG docker $USER
+```
+
+## Capabilities Detection
+
+The runner automatically detects and reports:
+- Operating system and architecture
+- Available shells (bash, sh, powershell)
+- Installed tools (node, python, go, etc.)
+- Docker availability
+- Disk space and network bandwidth
+
+These capabilities help admins understand what each runner can handle.
+
+## Troubleshooting
+
+### Runner not connecting
+
+1. Check network connectivity to your GitCaddy instance
+2. Verify the registration token is valid
+3. Check firewall rules allow outbound HTTPS
+
+### Jobs not running
+
+1. Verify runner labels match the job's `runs-on` requirement
+2. Check runner is online in the admin panel
+3. Review runner logs: `journalctl -u act_runner -f`
+
+## More Information
+
+- [act_runner Repository](https://git.marketally.com/gitcaddy/act_runner)
+- [GitCaddy Documentation](https://git.marketally.com/gitcaddy/gitea)