Developer Guide

Quick Start

This guide helps you spin up a complete Blood Kings Monitoring server stack in under two minutes.

Step 1: Start Central Server

Deploying via Docker Compose is the easiest route. Create a folder on your host VPS and create the compose file:

# docker-compose.yml
version: '3.8'
services:
  bloodkings:
    image: bkpepe/bloodkings:latest
    ports:
      - "8080:80"
    volumes:
      - ./data:/var/www/html/data
    restart: always

Run the compose stack using:

docker compose up -d

Once running, open your web browser to http://localhost:8080 and proceed with the initial admin account setup.

Step 2: Add Your First Monitor

Log in to your admin panel and use the Add monitor button above the monitors table. You can track URLs (HTTPS), TCP ports, Minecraft/TeamSpeak/Discord servers, or VPS host metrics. Note: the admin panel UI is currently Czech-only - English admin translation is planned.

System Requirements

Blood Kings is built to run on lightweight hardware profiles (e.g. Raspberry Pis, micro cloud nodes).

Central Server:

  • CPU: 1 vCPU (x86_64 or ARM64)
  • Memory: 128 MB RAM (256 MB recommended)
  • Storage: 50 MB application core + SQLite database history size
  • Non-DockerLAMP: PHP 8.2+, Apache/Nginx, mod_rewrite config, and a MySQL/MariaDB daemon.

Remote Agent:

  • OS: Linux (any system with Bash and Curl), Windows 10/11/Server, macOS, or Raspberry Pi OS
  • Memory: Under 10 MB RAM footprint
  • Network: Outgoing HTTPS access (port 443) targeting your central server URL

Architecture Overview

Blood Kings combines active pings (server-side polling) and passive telemetry reports (pushed from agents).

Remote Agent(Linux/Windows/Docker)↓ HTTPS POST (Metrics)
Central Server(PHP / SQLite or MySQL)↓ Render Static API
Public Status Page(HTML / cached JSON)

Passive Telemetry (Agents): The agent daemon runs locally on monitored boxes. Every 60 seconds, it fetches system resource parameters (CPU, memory, storage loads) and reports them back to the central server via secure POST requests. This means you do not have to expose open incoming firewall ports on the monitored hosts.

Active Probing (Pinger): The central server initiates cron runs to ping targets (HTTP/HTTPS, TCP connection checks, ICMP pings) directly from server threads.