nerd-monitor/RELEASE.md

# Nerd Monitor - Release & Deployment Guide

## Overview

This project uses **Gitea Actions** to automatically build and release cross-platform binaries when you push to the `master` branch or create a new tag.

## Automatic Release Pipeline

### How It Works

1. **Master Branch Push**: When you push to `master`, the workflow:
   - Builds all platform binaries (Linux/macOS/Windows, amd64/arm64)
   - Generates checksums (SHA256)
   - Binaries are available as build artifacts for 30 days

2. **Tag Creation**: When you create a tag (e.g., `v1.0.0`), the workflow:
   - Does all of the above
   - Creates a Gitea Release
   - Uploads all binaries and checksums to the release (permanent storage)

### Supported Platforms

Binaries are built for:
- **Linux**: amd64, arm64
- **macOS**: amd64 (Intel), arm64 (Apple Silicon)
- **Windows**: amd64

### What Gets Built and Released

When you push a tag, the workflow automatically creates:

**Binaries** (10 files total):
- `nerd-monitor-server-linux-amd64` - Server for Linux x86_64
- `nerd-monitor-server-linux-arm64` - Server for Linux ARM64 (Raspberry Pi, etc.)
- `nerd-monitor-server-darwin-amd64` - Server for macOS Intel
- `nerd-monitor-server-darwin-arm64` - Server for macOS Apple Silicon
- `nerd-monitor-server-windows-amd64.exe` - Server for Windows
- `nerd-monitor-agent-linux-amd64` - Agent for Linux x86_64
- `nerd-monitor-agent-linux-arm64` - Agent for Linux ARM64
- `nerd-monitor-agent-darwin-amd64` - Agent for macOS Intel
- `nerd-monitor-agent-darwin-arm64` - Agent for macOS Apple Silicon
- `nerd-monitor-agent-windows-amd64.exe` - Agent for Windows

**Checksums**:
- `SHA256SUMS` - SHA256 checksums for all binaries (for verification)

## Workflow Configuration

The Gitea Actions workflow is defined in `.gitea/workflows/release.yml`

### Trigger Events
- Push to `master` or `main` branch (builds only, no release)
- Push of git tags (e.g., `v1.0.0`) - triggers full release with uploads

### Creating a Release

#### Step 1: Create and Push a Tag

```bash
# Create an annotated tag
git tag -a v1.0.0 -m "Release version 1.0.0"

# Push the tag to Gitea
git push origin v1.0.0
```

#### Step 2: Monitor the Workflow

1. Go to your repository on Gitea
2. Click the **Actions** tab
3. You'll see the workflow running:
   - `build` job: Compiles all binaries (5-10 minutes)
   - `docker-build` job: Builds Docker images (5-10 minutes)

#### Step 3: Verify the Release

Once the workflow completes:

1. Go to the **Releases** tab
2. You'll see a new release with:
   - All platform binaries (Linux, macOS, Windows)
   - SHA256SUMS file with checksums
   - Docker image files (.tar)

### What Gets Built and Released

When you push a tag, the workflow automatically:

**Binaries** (10 files total):
- `nerd-monitor-server-linux-amd64` - Server for Linux x86_64
- `nerd-monitor-server-linux-arm64` - Server for Linux ARM64 (Raspberry Pi, etc.)
- `nerd-monitor-server-darwin-amd64` - Server for macOS Intel
- `nerd-monitor-server-darwin-arm64` - Server for macOS Apple Silicon
- `nerd-monitor-server-windows-amd64.exe` - Server for Windows
- `nerd-monitor-agent-linux-amd64` - Agent for Linux x86_64
- `nerd-monitor-agent-linux-arm64` - Agent for Linux ARM64
- `nerd-monitor-agent-darwin-amd64` - Agent for macOS Intel
- `nerd-monitor-agent-darwin-arm64` - Agent for macOS Apple Silicon
- `nerd-monitor-agent-windows-amd64.exe` - Agent for Windows

**Checksums**:
- `SHA256SUMS` - SHA256 checksums for all binaries (for verification)

## Local Building

You can also build binaries locally:

```bash
# Build for current platform
make build

# Build for all platforms
make build-all

# Clean build artifacts
make clean
```

Binaries are created in the `bin/` directory.

## Docker Images (Manual Build)

Docker images are available but not built automatically by CI/CD. To build them manually:

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

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

# Or use Docker Compose
docker-compose build

# Or use Docker Compose to run both
docker-compose up
```

See `DOCKER_COMPOSE.md` and `QUICKSTART.md` for detailed instructions.

## Gitea Configuration

### Prerequisites

Before the CI/CD pipeline can create releases automatically, you need to:

1. **Ensure Gitea Actions is enabled** on your Gitea server
2. **Create a Gitea API Token** with release permissions
3. **Add the token as an Actions secret** in your repository

### Setup Instructions

#### 1. Enable Gitea Actions (Server Admin)

SSH into your Gitea server and verify Actions is enabled:

```bash
# Edit the Gitea configuration
sudo vi /etc/gitea/app.ini

# Add or verify:
[actions]
ENABLED = true
```

Then restart Gitea:
```bash
sudo systemctl restart gitea
```

#### 2. Create an API Token

1. Log in to Gitea with your user account
2. Go to **Settings** → **Applications**
3. Click **Generate New Token**
4. Fill in:
   - **Token Name**: `release-automation` (or any descriptive name)
   - **Scopes**: Select `repo` (full repository access)
5. Click **Generate Token**
6. **Copy the token** (you won't be able to see it again)

#### 3. Add Token as Repository Secret

1. Go to your repository on Gitea
2. Navigate to **Settings** → **Secrets**
3. Click **Add Secret**
4. Fill in:
   - **Secret Name**: `GITEA_TOKEN`
   - **Secret Value**: Paste the token you copied
5. Click **Save**

Now the workflow will be able to create releases automatically!

### Workflow Configuration

The Gitea Actions workflow is defined in `.gitea/workflows/release.yml`

### Trigger Events
- Push to `master` or `main` branch (builds only, no release)
- Push of git tags (e.g., `v1.0.0`) - triggers full release with uploads

Each release includes:

```
nerd-monitor-server-linux-amd64
nerd-monitor-server-linux-arm64
nerd-monitor-server-darwin-amd64
nerd-monitor-server-darwin-arm64
nerd-monitor-server-windows-amd64.exe

nerd-monitor-agent-linux-amd64
nerd-monitor-agent-linux-arm64
nerd-monitor-agent-darwin-amd64
nerd-monitor-agent-darwin-arm64
nerd-monitor-agent-windows-amd64.exe

SHA256SUMS (checksums for all binaries)
```

## Deployment Options

### Option 1: Use Pre-Built Binaries (Recommended)
Download the native binaries from the Releases tab and run directly:
- Smallest footprint
- No Docker required
- Easiest to deploy to existing machines

### Option 2: Use Docker (Manual Build)
Build Docker images manually and deploy:
```bash
docker build -t nerd-monitor-server:latest -f Dockerfile.server .
docker run -p 8080:8080 nerd-monitor-server:latest
```

See `docker-compose.yml` for running both server and agent together.

### Option 3: Use Docker Compose
For quick development/testing with both server and agent:
```bash
docker-compose up
```

See `DOCKER_COMPOSE.md` and `QUICKSTART.md` for details.

## Troubleshooting

### Workflow Not Triggering

**Problem**: I pushed a tag but the workflow didn't start

**Solutions**:
1. Check that the tag is pushed: `git push origin v1.0.0`
2. Verify Gitea Actions is enabled: Settings → Actions → Status should show "Enabled"
3. Check Actions tab for any error messages
4. Ensure your runner is online: Settings → Runners

### Token Authentication Failed

**Problem**: `"message":"Unauthorized"` or token-related errors in the logs

**Solutions**:
1. Verify the `GITEA_TOKEN` secret is set correctly: Repository → Settings → Secrets
2. Ensure the token has `repo` scope permissions
3. Token should not be expired - regenerate if needed
4. Double-check there are no extra spaces in the token

### Build Fails with "Go not found"

**Problem**: Workflow fails when trying to build, says Go is not available

**Solutions**:
1. This is usually a temporary issue - runner environment might not have been fully initialized
2. Retry the workflow: Go to Actions tab → Click the failed workflow → Click "Re-run jobs"
3. Check if the runner has enough disk space: `df -h` on the runner machine

### Binaries Not Uploaded to Release

**Problem**: Workflow completes but binaries don't appear in the release

**Solutions**:
1. Check the workflow logs: Actions tab → Click the workflow → View logs
2. Look for "Uploading" messages and any error messages
3. Verify the release was created: Go to Releases tab
4. Check that `GITEA_TOKEN` secret is still valid (tokens can expire)

### How to Check Workflow Logs

1. Go to your Gitea repository
2. Click the **Actions** tab
3. Click on the workflow run (should show the tag name)
4. Click on the `build` job
5. Scroll through the log to find error messages
6. Look for red `❌` marks indicating failures

### Manual Trigger for Testing

If you want to test the workflow without creating a full release:

```bash
# Push to main/master branch (triggers build only, no release)
git push origin main

# Then push a tag when you're ready (triggers full release)
git tag -a v1.0.0 -m "Release"
git push origin v1.0.0
```

## Additional Resources

- [Gitea Actions Documentation](https://docs.gitea.io/en-us/actions/)
- [Project README](./README.md)
- [Quick Start Guide](./QUICKSTART.md)
- [Agent Guidelines](./AGENTS.md)
- [Docker Compose Guide](./DOCKER_COMPOSE.md)