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

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

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

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

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

# Add or verify:
[actions]
ENABLED = true

Then restart Gitea:

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:

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:

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:

# 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
• Project README
• Quick Start Guide
• Agent Guidelines
• Docker Compose Guide