nevr-fleetmanager

A production-ready Go 1.25 fleet manager service for managing WebSocket connections and real-time communication with Nakama integration.

Features

• 🚀 Go 1.25 with modern language features
• 📦 Idiomatic Project Layout following Go community standards
• 🔌 WebSocket Support using gorilla/websocket
• 🎮 Nakama Integration for real-time multiplayer communication
• ⚙️ Flexible Configuration via YAML files, environment variables, and command-line flags
• 🔐 Environment Variables support with dotenv
• 📝 Structured Logging using uber-go/zap
• 🐳 Docker Support with optimized Alpine-based multi-stage builds
• 🔄 Docker Compose for easy local development
• 🤖 GitHub Actions CI/CD pipeline with automatic container builds
• 📦 Container Registry automatic pushes to ghcr.io
• 🏷️ Semantic Versioning built into the release process
• 📋 Conventional Commits for consistent commit messages
• 🧪 Comprehensive Test Suite with 85%+ coverage target
• 👤 Non-root Container execution for security
• 🏥 Health Checks for container orchestration
• 📚 Comprehensive Documentation including agent guidelines

Quick Start

Prerequisites

• Go 1.25 or later
• Docker and Docker Compose (optional, for containerization)
• Git

Installation

1. Clone the repository:

git clone https://github.com/EchoTools/nevr-fleetmanager.git
cd nevr-fleetmanager

2. Copy the environment template:

cp .env.example .env

3. Install dependencies:

go mod download

4. Run the application:

go run cmd/app/main.go

Usage

Running Locally

Run with default configuration:

go run cmd/app/main.go

Run with custom configuration file:

go run cmd/app/main.go --config configs/config.yaml

Show version information:

go run cmd/app/main.go --version

Building

Build the binary:

go build -o bin/app ./cmd/app

Build with version information:

VERSION=$(git describe --tags --always --dirty)
COMMIT=$(git rev-parse --short HEAD)
BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ')

go build -ldflags="-X github.com/echotools/nevr-fleetmanager/pkg/version.Version=${VERSION} \
                    -X github.com/echotools/nevr-fleetmanager/pkg/version.Commit=${COMMIT} \
                    -X github.com/echotools/nevr-fleetmanager/pkg/version.BuildDate=${BUILD_DATE}" \
         -o bin/app ./cmd/app

Running with Docker

Build and run with Docker Compose:

docker-compose up --build

Or build and run manually:

docker build -t nevr-fleetmanager:latest .
docker run -p 8080:8080 nevr-fleetmanager:latest

Testing

Run tests:

go test -v ./...

Run tests with coverage:

go test -v -race -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Run tests with race detection:

go test -race ./server/

Configuration

The application supports multiple configuration sources with the following priority (highest to lowest):

1. Command-line flags
2. Environment variables
3. Configuration file (YAML)
4. Default values

Configuration File

Create a config.yaml file:

name: nevr-fleetmanager
port: 8080

logger:
  level: info      # debug, info, warn, error
  format: json     # json, console
  output: stdout   # stdout, stderr, or file path
  stacktrace: false

Environment Variables

Set environment variables directly or use a .env file:

APP_NAME=nevr-fleetmanager
APP_PORT=8080
LOG_LEVEL=debug
LOG_FORMAT=console
LOG_OUTPUT=stdout

Command-Line Flags

./app --config /path/to/config.yaml
./app --version

Project Structure

.
├── cmd/                      # Command-line applications
│   └── app/                 # Main application
│       └── main.go          # Application entry point
├── internal/                # Private application code
│   ├── config/             # Configuration management
│   │   └── config.go       # Config loading and parsing
│   └── logger/             # Logging setup
│       └── logger.go       # Zap logger initialization
├── pkg/                     # Public packages (can be imported by other projects)
│   └── version/            # Version information
│       └── version.go      # Version variables
├── server/                  # Fleet manager server implementation
│   ├── fleetmanager.go     # Main FleetManager logic
│   ├── handlers.go         # WebSocket handlers
│   └── *_test.go           # Test files
├── rtapi/                   # Real-time API protocol buffers
├── configs/                 # Configuration files
│   └── config.yaml         # Default configuration
├── docs/                    # Documentation
│   ├── CODING_AGENT_INSTRUCTIONS.md  # Test implementation guidelines
│   ├── TASK_INDEX.md       # Test suite task breakdown
│   └── tasks/              # Detailed task specifications
├── .github/                 # GitHub-specific files
│   └── workflows/          # GitHub Actions workflows
│       └── build.yml       # Container build and push workflow
├── .env.example            # Example environment variables
├── .dockerignore           # Docker build exclusions
├── .gitignore              # Git exclusions
├── docker-compose.yml      # Docker Compose configuration
├── Dockerfile              # Container image definition
├── go.mod                  # Go module definition
├── go.sum                  # Go module checksums
├── Makefile                # Build automation
├── AGENTS.md               # Guidelines for AI agents
├── README.md               # This file
└── LICENSE                 # MIT License

Development

Commit Messages

This project follows Conventional Commits:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

• feat: New feature (MINOR version bump)
• fix: Bug fix (PATCH version bump)
• docs: Documentation changes
• style: Code style changes
• refactor: Code refactoring
• perf: Performance improvements
• test: Test additions or updates
• build: Build system changes
• ci: CI/CD changes
• chore: Other changes

Breaking Changes: Add ! after type or BREAKING CHANGE: in footer (MAJOR version bump):

feat!: remove deprecated API endpoints

BREAKING CHANGE: The v1 API has been removed. Use v2 endpoints.

Versioning

This project follows Semantic Versioning:

• MAJOR: Breaking changes
• MINOR: New features (backward-compatible)
• PATCH: Bug fixes (backward-compatible)

Release Process

1. Update version if needed
2. Commit changes with conventional commit message
3. Create and push a tag:

   git tag -a v1.0.0 -m "chore(release): version 1.0.0"
   git push origin v1.0.0

4. GitHub Actions will automatically build and push the container image

CI/CD

GitHub Actions

The project includes a comprehensive CI/CD pipeline:

• On Push to Main: Builds and pushes container with latest tag
• On Tag Push (v*): Builds and pushes with semantic version tags
• On Pull Request: Builds container (doesn't push)

Container Registry

Images are automatically pushed to GitHub Container Registry:

• ghcr.io/echotools/nevr-fleetmanager:latest
• ghcr.io/echotools/nevr-fleetmanager:v1.0.0
• ghcr.io/echotools/nevr-fleetmanager:v1.0
• ghcr.io/echotools/nevr-fleetmanager:v1

Pulling Images

docker pull ghcr.io/echotools/nevr-fleetmanager:latest
docker run -p 8080:8080 ghcr.io/echotools/nevr-fleetmanager:latest

Architecture

Fleet Manager

The core fleet manager handles:

• WebSocket connection lifecycle management
• Real-time message routing
• Session state tracking
• Health monitoring and metrics
• Integration with Nakama real-time API

Configuration System

Inspired by Heroic Labs Nakama, the configuration system supports:

• YAML configuration files
• Environment variable overrides
• Command-line flag overrides
• Sensible defaults
• Hierarchical configuration structure

Logging

Uses uber-go/zap for high-performance structured logging:

• JSON or console output formats
• Multiple output destinations (stdout, stderr, file)
• Configurable log levels
• Caller information
• Optional stack traces
• Structured fields for better observability

Container Design

• Multi-stage build: Separates build and runtime environments
• Alpine base: Minimal image size (~10MB)
• Non-root user: Enhanced security
• Health checks: Ready for orchestration
• CA certificates: HTTPS support
• Timezone data: Proper time handling

Testing

Test Suite Roadmap

The project includes a comprehensive test suite implementation plan:

• Current Coverage: 45%
• Target Coverage: 85%+
• Test Files: Located in server/*_test.go
• Documentation: See docs/CODING_AGENT_INSTRUCTIONS.md and docs/TASK_INDEX.md

Running Tests

# Run all tests
go test -v ./...

# Run with coverage
go test -v -coverprofile=coverage.out ./...

# Run with race detection
go test -race ./server/

# View coverage report
go tool cover -html=coverage.out

Security

• Non-root container execution
• No hardcoded secrets
• Environment variable support
• Minimal attack surface (Alpine)
• Regular dependency updates
• Security scanning in CI/CD

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes using conventional commits
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

See AGENTS.md for detailed development guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Heroic Labs Nakama for configuration system inspiration and real-time API
• uber-go/zap for excellent logging library
• gorilla/websocket for WebSocket implementation
• Conventional Commits for commit message standards
• Semantic Versioning for version management
• Go community for project layout standards

Resources

• Go Project Layout
• Effective Go
• Uber Go Style Guide
• Conventional Commits
• Semantic Versioning

Support

For issues, questions, or contributions, please open an issue on GitHub.