nerd-monitor/RELEASE.md

Nerd Monitor - Release & Deployment Guide

Overview

This project uses Gitea Actions to automatically build and release binaries and Docker images 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)
   • Uploads artifacts for 30 days
   • Builds Docker images (server & agent)

2. Tag Creation: When you create a tag (e.g., v1.0.0), the workflow:

   • Does all of the above
   • Creates a GitHub Release
   • Uploads all binaries and Docker images to the release

Supported Platforms

Binaries are built for:

• Linux: amd64, arm64
• macOS: amd64 (Intel), arm64 (Apple Silicon)
• Windows: amd64

Docker images are built for Linux containers.

Workflow Configuration

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

Trigger Events

• Push to master branch
• Push of git tags (e.g., v1.0.0)

Jobs

• build: Compiles all platform binaries and generates checksums
• docker-build: Builds Docker images for server and agent

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)

Docker Images:

• nerd-monitor-server-v1.0.0.tar - Server Docker image (can be imported)
• nerd-monitor-agent-v1.0.0.tar - Agent Docker image (can be imported)

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

Two Docker images are built:

Server Image

docker pull nerd-monitor-server:latest
docker run -p 8080:8080 nerd-monitor-server

Agent Image

docker pull nerd-monitor-agent:latest
docker run nerd-monitor-agent --server your-server:8080

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)

Coolify Integration

If you want to use Coolify for deployment:

1. For Server Deployment:

   • Use Dockerfile.server as the build context
   • Coolify will auto-build on master branch pushes
   • Deploy the server container to Coolify

2. For Agent Deployment:

   • Use Dockerfile.agent as the build context
   • Deploy the agent container to machines that need monitoring

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)

Docker Image Build Fails

Problem: docker-build job fails

Solutions:

1. Verify Docker is installed on the runner: SSH to runner and run docker --version
2. Check if the Dockerfile has syntax errors: docker build -f Dockerfile.server .
3. Ensure runner has enough disk space for building: docker system df
4. Check Docker daemon is running: sudo systemctl status docker

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 job that failed (build or docker-build)
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