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

Option 1: Automatic Release (Recommended)

1. Create a new tag:

git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

2. Gitea Actions will automatically:

   • Build all binaries
   • Create a release in Gitea
   • Upload all artifacts

3. View the release in Gitea: Releases tab on your repository

Option 2: Manual Release Upload

If you need to manually upload binaries to Gitea:

# Set your Gitea token (create one in Gitea Settings → Applications → Generate Token)
export GITEA_TOKEN=your_token_here

# Build all binaries
make build-all

# Upload to release
./scripts/upload-release.sh v1.0.0

Environment variables (optional):

• GITEA_URL: Gitea server URL (default: https://git.nerdnest.dev)
• REPO_OWNER: Repository owner (default: ducky)
• REPO_NAME: Repository name (default: nerd-monitor)

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

Enable Gitea Actions

1. SSH into your Gitea server
2. Edit app.ini:

[actions]
ENABLED = true

3. Restart Gitea:

systemctl restart gitea

Create an API Token (for manual uploads)

1. Go to Settings → Applications
2. Click "Generate New Token"
3. Name it (e.g., "Release Upload")
4. Give it repo permissions
5. Copy the token

Use it with the upload script:

./scripts/upload-release.sh v1.0.0 <your_token>

Release Files

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

Actions not running

• Ensure Gitea Actions is enabled on your server
• Check that your runner is available (Settings → Actions)
• Review action logs in the Actions tab

Release not created

• Ensure the tag format matches semantic versioning (v1.0.0)
• Check workflow logs for build errors
• Verify Go 1.24.4 is available in the runner environment

Docker images not building

• Ensure Docker/Buildx is available in the runner
• Check the Dockerfile syntax
• Review build logs in the Actions tab

Additional Resources

• Gitea Actions Documentation
• Project README
• Quick Start Guide
• Agent Guidelines