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)

Docker is **not required** for the CI/CD pipeline. Binary builds work without Docker.

If you want to manually build Docker images:

```bash
# Build server image
docker build -t nerd-monitor-server -f Dockerfile.server .

# Build agent image
docker build -t nerd-monitor-agent -f Dockerfile.agent .

# Or use docker-compose for both
docker-compose build
docker-compose up
```

## What Happens Next

Once you've set everything up:

1. **Every push to main/master** triggers the build job:
   - Compiles all platform binaries (Linux, macOS, Windows)
   - Creates SHA256 checksums
   - Artifacts available for 30 days

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 (permanent storage)

3. **Releases are available in**:
   - Repository Releases tab in Gitea
   - All binaries ready for download
   - SHA256SUMS file for verification

Note: Docker images are not built automatically. To build Docker images manually, use:
```bash
docker build -t nerd-monitor-server -f Dockerfile.server .
docker build -t nerd-monitor-agent -f Dockerfile.agent .
# Or use docker-compose: docker-compose build
```

## Troubleshooting

### "docker: command not found" in workflow
- Docker support is not required - the workflow builds binaries without it
- Binary builds will always succeed
- Docker images must be built manually using: `docker build -f Dockerfile.server .`
- See QUICKSTART.md or DOCKER_COMPOSE.md for manual Docker build instructions

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