GoKuma Documentation

Welcome to the official GoKuma documentation. GoKuma is a self-hosted, lightweight, high-performance uptime monitoring system engineered entirely in pure Go.

Check Zero External Runtime Registries
GoKuma is designed for complete operational autonomy. It can be built and deployed without pulling from Docker Hub or external container registries.

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.

Security Cryptographic Secrets Provisioning
Run ./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