9184de0a1d
- Create Dockerfile for server with multi-stage build - Create Dockerfile for agent with multi-stage build - Set up Gitea Actions workflow to automatically build and release binaries - Build for all platforms: Linux (amd64/arm64), macOS (amd64/arm64), Windows (amd64) - Generate checksums for all release artifacts - Include Docker image building in CI/CD pipeline - Add release upload script for manual Gitea releases - Add comprehensive RELEASE.md documentation
197 lines
4.5 KiB
Markdown
197 lines
4.5 KiB
Markdown
# 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:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```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
|
|
|
|
Two Docker images are built:
|
|
|
|
### Server Image
|
|
```bash
|
|
docker pull nerd-monitor-server:latest
|
|
docker run -p 8080:8080 nerd-monitor-server
|
|
```
|
|
|
|
### Agent Image
|
|
```bash
|
|
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`:
|
|
```ini
|
|
[actions]
|
|
ENABLED = true
|
|
```
|
|
3. Restart Gitea:
|
|
```bash
|
|
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:
|
|
```bash
|
|
./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](https://docs.gitea.io/en-us/actions/)
|
|
- [Project README](./README.md)
|
|
- [Quick Start Guide](./QUICKSTART.md)
|
|
- [Agent Guidelines](./AGENTS.md)
|