nerd-monitor/GITEA_SETUP.md

# 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 and 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

### Installing Docker on the Runner (Optional)

If you want to build Docker images as part of your releases, install Docker on the runner:

```bash
# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add permissions for the runner user to use Docker
sudo usermod -aG docker $USER

# Verify Docker is working
docker --version

# Note: You may need to logout and login for group permissions to take effect
```

**Without Docker**: The binary builds will still work. Only Docker image generation will be skipped (the workflow will show a warning but still succeed).

## What Happens Next

Once you've set everything up:

1. **Every push to main/master** triggers the build job:
   - Compiles all platform binaries
   - Attempts to build Docker images (skips if Docker unavailable)
   - 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 checksums to the release
   - Uploads Docker images if available

3. **Releases are available in**:
   - Repository Releases tab in Gitea
   - Binaries ready for download
   - Docker images (if Docker is available on runner)

## Troubleshooting

### "docker: command not found" in workflow
- Docker is not installed on your runner
- This is **optional** - binaries will still build
- If you want Docker images, install Docker on the runner (see above)
- The workflow will gracefully skip Docker builds and show a warning

### "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 Go installed (1.24.4 or later)
- Docker is optional (for building Docker images)
- 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 (Docker)
- Make sure the runner user 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

## Support

- Gitea Actions Docs: https://docs.gitea.io/en-us/actions/
- Act Runner Docs: https://gitea.com/gitea/act_runner
- Docker Installation: https://docs.docker.com/install/
- For issues with the workflow itself, check the Actions tab logs