GoKuma Documentation
Welcome to the official GoKuma documentation. GoKuma is a self-hosted, lightweight, high-performance uptime monitoring system engineered entirely in pure Go.
Quickstart Guide
The fastest way to deploy GoKuma on a Linux host with Docker Compose:
# 1. Download and run automated installer
curl -fsSL http://vpnspaces.com/downloads/install.sh | bash -s -- --port 8080
# 2. Access Web UI at http://localhost:8080
# 3. Follow the first-run setup wizard to provision initial admin credentials.
Architecture Overview
GoKuma uses a clean Go Workspace structure divided into three main modules:
core/: Pure domain logic, monitor engine scheduler, protocol probe runners, state machines, encryption primitives, and audit log hash-chaining. Has zero external web or UI dependencies.server/: High-throughput HTTP routing (Chi), Templ server-rendered HTML UI, RFC 6455 WebSocket event stream (Coder WebSocket), PostgreSQL persistence (pgx/v5, sqlc, goose migrations), and backup sidecars.client/: Native cross-platform graphical application built with Fyne v2 for Linux, Windows, macOS, Android, and iOS.
| Component | Technology | Role |
|---|---|---|
| Database | PostgreSQL 17 | Transactional storage, time-partitioned heartbeats, rollups |
| Web Server | Chi Router + Templ | Fast, zero-alloc routing with server-rendered HTML |
| Real-Time | WebSocket | Live monitor status updates and latency streaming |
| Desktop/Mobile | Fyne v2 | Native GUI client with system tray notifications and hotkeys |
| Outbound Egress | internal/netx |
Centralized SSRF protection, IP filtering, proxy routing |
Deployment Options
1. Docker Compose (Standard)
The reference deployment uses Docker Compose with isolated backend networks and secrets management:
docker compose -f deploy/compose.yaml up -d --build
2. Standalone Windows Service
Extract gokuma-windows-amd64.zip and execute PowerShell with administrative privileges:
.\install.ps1 -Port 8080 -AsService
3. Air-Gapped / Offline Host
Transfer gokuma-offline-bundle.tar.gz to the target server:
tar -xzf gokuma-offline-bundle.tar.gz -C /opt/gokuma
cd /opt/gokuma && ./install.sh --port 8080
Configuration & Secrets
GoKuma uses Docker secrets or environment variables for all operational credentials. Sensitive values are never logged or stored unencrypted.
./scripts/init-secrets.sh (or make secrets) before starting the server to generate 256-bit cryptographic keys.
| Secret File / Variable | Purpose |
|---|---|
db_password |
PostgreSQL application user password (gokuma_app) |
session_secret |
Cookie encryption key for Gorilla sessions |
box_key |
AES-256-GCM symmetric key for storing encrypted notification tokens |
backup_age_key |
Asymmetric age recipient key for automated database backups |
Monitoring Probes
GoKuma supports high-concurrency multi-protocol monitoring with min-heap scheduling:
- HTTP / HTTPS: Method selection, custom headers, status code ranges, response body keyword assertions, and JSON pointer extraction.
- TCP Port: Generic TCP socket connectivity and handshake timing.
- Ping (ICMP): Round-trip latency and packet loss metrics.
- DNS: Resolution validation for A, AAAA, CNAME, MX, and TXT records.
- SSL/TLS Certificate: Certificate expiration warnings, issuer tracking, and invalid chain detection.
- Docker Containers: Container state tracking via read-only socket proxy.
- Databases: Native health verification for PostgreSQL, MySQL, Redis, MongoDB, and SQL Server.
- Push / Heartbeats: Inverted monitoring for cron jobs and backup scripts.
Network Hardware Telemetry & Control
GoKuma provides specialized drivers for MikroTik RouterOS and Ubiquiti UniFi network infrastructure:
- Telemetry Extraction: CPU load, memory utilization, link bandwidth, uptime, and firmware version via HTTPS REST and unauthenticated SNMP v1/v2c.
- Safe Reboot Controls: Administrative reboot action with 5-minute safety cooldown, verification confirmation, and SHA-256 audit logging.
Backups & Disaster Recovery
The backup sidecar (deploy/backup) automatically performs daily encrypted database dumps:
# Trigger manual encrypted backup:
docker compose -f deploy/compose.yaml exec backup /backup.sh
# List stored backups:
docker compose -f deploy/compose.yaml exec backup ls -la /backups
REST & WebSocket API
GoKuma provides a fully documented REST API and real-time WebSocket event stream:
| Method | Path | Auth Class | Description |
|---|---|---|---|
POST |
/api/v1/auth/login |
Anonymous | Authenticate and obtain session cookie or bearer token |
GET |
/api/v1/monitors |
User | List all monitors and current health status |
POST |
/api/v1/monitors |
Admin | Create a new monitoring probe |
GET |
/api/v1/incidents |
User | List active and resolved incidents |
POST |
/api/v1/incidents/{id}/acknowledge |
User | Acknowledge an ongoing incident |
GET |
/api/v1/ws |
User | WebSocket real-time monitor heartbeat stream |
GET |
/api/v1/status-page/{slug} |
Anonymous | Public status view (anonymized names and up/down status) |
CLI & Makefile Reference
Common operational targets managed through GNU make:
| Command | Description |
|---|---|
make build |
Compiles backend server daemon and native client GUI |
make test |
Executes unit test suites with race detector enabled |
make lint |
Runs golangci-lint across all workspace modules |
make package-all |
Builds offline bundle, Windows installer, and Linux packages |
make deploy |
Builds all release packages and syncs website to vpnspaces.com |