From 6c6bc0d57fac4a7c317c1e97bd10b8d4b3a6a56c Mon Sep 17 00:00:00 2001
From: Ducky SSH User <ducky@DLO-DEV-001.nerdnest.lan>
Date: Sat, 20 Dec 2025 06:06:21 +0000
Subject: [PATCH] Add Gitea server setup guide

- Document GITEA_TOKEN secret configuration
- Provide API token creation instructions
- Include Gitea Actions enablement steps
- Add runner verification and setup instructions
- Include testing procedures for the complete setup
- Add troubleshooting for common configuration issues
- Explain the workflow execution flow after setup
---
 GITEA_SETUP.md | 151 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 151 insertions(+)
 create mode 100644 GITEA_SETUP.md

diff --git a/GITEA_SETUP.md b/GITEA_SETUP.md
new file mode 100644
index 0000000..60b4ac9
--- /dev/null
+++ b/GITEA_SETUP.md
@@ -0,0 +1,151 @@
+# Gitea Actions Setup - Server Configuration Checklist
+
+This document outlines the changes needed on your Gitea server to make the CI/CD pipeline work.
+
+## What You Need to Do
+
+### 1. Add GITEA_TOKEN Secret to Repository
+
+1. **Log into Gitea** with your user account
+2. **Navigate to** your nerd-monitor repository
+3. **Go to Settings → Secrets**
+4. **Create a new secret**:
+   - Name: `GITEA_TOKEN`
+   - Value: [Your Gitea API token - see below for how to create]
+5. **Save the secret**
+
+### 2. Create an API Token (if you haven't already)
+
+1. **Log into Gitea** with your user account
+2. **Go to Settings → Applications**
+3. **Click "Generate New Token"**
+4. **Fill in the form**:
+   - Token Name: `release-automation`
+   - Scopes: Select at least `repo` (full repository access)
+5. **Click "Generate"**
+6. **Copy the token immediately** (you won't see it again)
+7. **Use this token** for the secret in step 1
+
+### 3. Verify Gitea Actions is Enabled (Server Admin)
+
+These steps require SSH access to your Gitea server:
+
+```bash
+# SSH into your Gitea server
+ssh user@your-gitea-server
+
+# Edit the Gitea configuration
+sudo vi /etc/gitea/app.ini
+
+# Verify or add this section:
+[actions]
+ENABLED = true
+
+# Save and exit (Esc, :wq, Enter)
+
+# Restart Gitea for changes to take effect
+sudo systemctl restart gitea
+```
+
+### 4. Verify Your Runner is Online (Server Admin)
+
+1. **Log into Gitea** as admin
+2. **Go to Administration → Actions → Runners**
+3. **Verify** at least one runner is listed and shows as "Online" or "Idle"
+4. If no runners:
+   - You need to set up a Gitea Actions runner on a machine with Docker and Go
+   - See "Setting Up a Runner" below
+
+## Setting Up a Runner (if needed)
+
+If you don't have any runners yet, you need to set one up. This can be on the Gitea server itself or any machine with Docker/Go.
+
+### Quick Runner Setup
+
+1. **On your Gitea server or runner machine**:
+
+```bash
+# Download the Gitea Actions runner
+wget https://github.com/gitea/act_runner/releases/download/v0.6.10/act_runner-0.6.10-linux-amd64
+chmod +x act_runner-0.6.10-linux-amd64
+
+# Register the runner with your Gitea instance
+./act_runner-0.6.10-linux-amd64 register \
+  --instance https://git.nerdnest.dev \
+  --token <your-runner-token>
+
+# Run the runner in the background
+./act_runner-0.6.10-linux-amd64 daemon &
+```
+
+To get a runner token:
+1. Log into Gitea as **admin**
+2. Go to **Administration → Actions → Runners**
+3. Click **Create new runner**
+4. Follow the registration steps
+
+## Testing the Setup
+
+Once everything is configured:
+
+1. **Push a test tag**:
+```bash
+git tag -a v0.0.1-test -m "Test release"
+git push origin v0.0.1-test
+```
+
+2. **Monitor the build**:
+   - Go to Actions tab
+   - You should see the workflow running
+   - Check logs for any errors
+
+3. **Verify the release**:
+   - Go to Releases tab
+   - You should see a new release with binaries and checksums
+
+## Troubleshooting
+
+### "Action not found" error
+- Make sure Gitea Actions is enabled
+- Restart Gitea if you just enabled it: `sudo systemctl restart gitea`
+
+### No runners available
+- Runner must be registered: Administration → Actions → Runners
+- Runner machine must have Docker and Go installed
+- Check if runner is online in the UI
+
+### "GITEA_TOKEN" not found
+- Make sure the secret is named exactly `GITEA_TOKEN` (case-sensitive)
+- Go to Settings → Secrets and verify it's there
+- If it's there, try re-running the workflow
+
+### Build fails with permission denied
+- Make sure the runner has permission to run Docker commands
+- On the runner machine: `sudo usermod -aG docker $USER`
+- Logout and log back in for the group change to take effect
+
+## What Happens Next
+
+Once you've set everything up:
+
+1. **Every push to main/master** triggers the build job:
+   - Compiles all platform binaries
+   - Builds Docker images
+   - Uploads artifacts as build artifacts
+
+2. **Every git tag push** (e.g., `v1.0.0`) triggers the full release:
+   - Does all of the above
+   - Creates a Gitea Release
+   - Uploads all binaries and Docker images to the release
+   - Generates SHA256 checksums
+
+3. **Releases are available in**:
+   - Repository Releases tab in Gitea
+   - Binaries ready for download
+   - Docker images ready for import
+
+## Support
+
+- Gitea Actions Docs: https://docs.gitea.io/en-us/actions/
+- Act Runner Docs: https://gitea.com/gitea/act_runner
+- For issues with the workflow itself, check the Actions tab logs