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/monitoring: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, VPS host metrics, or heartbeats from jobs that report in on their own. 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).

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.

Central Server Database Config

Blood Kings Monitoring connects to standard MySQL or MariaDB database servers using PDO. Configure your database details inside status/config.php:

define('DB_HOST', '127.0.0.1');
define('DB_NAME', 'bloodkings_status');
define('DB_USER', 'bloodkings_user');
define('DB_PASS', 'YourStrongPassword123!');
define('TIMEZONE', 'Europe/Prague');

Environment Variables & Tokens

Essential security keys can be configured directly in config.php or via environment variables:

• cron_key: Secret key authorizing cron.php execution from external webhooks or timers.
• agent_registration_token: Shared secret authorizing automatic agent auto-registration.
• metrics_token: Bearer token protecting Prometheus metrics.php endpoint.

Public Status Pages & Branding

Customize public status pages directly inside the Admin Panel (Settings -> Branding). You can upload a custom logo, set accent color themes, and configure 24h / 7d / 30d SLA aggregation caching.

Heartbeat Monitors

Active checks only reach what is reachable over the network. A backup that runs at 3 AM and fails silently is invisible to them - there is nothing to ping. Heartbeat monitors invert the direction: the job reports in, and the monitor goes down when it stays silent.

Create a monitor of type Heartbeat, set how often the job should report, then call the URL it gives you at the end of your job:

curl -fsS -m 10 "https://your-server/status/heartbeat.php?token=YOUR_TOKEN"

If the job itself fails, say so explicitly - the monitor then goes down immediately instead of waiting out the interval:

curl -fsS -m 10 "https://your-server/status/heartbeat.php?token=YOUR_TOKEN&status=fail&msg=tar%20exited%202"

A monitor that has never received a signal reports unknown, not down. It is not failing - nothing is known about it yet, and alerting on an outage that never happened is its own kind of lie.

The token is the only thing authorising the endpoint. Keep it out of shared logs; if it leaks, anyone can report in on your behalf and the monitor will stay green while the backup is long dead.

Watchdog: who watches the collector

Everything is collected by one cron job. If that job dies, the application does not crash - it keeps serving the last known states and looks perfectly healthy. Of all the ways monitoring can fail, this is the worst, because it never announces itself.

The server therefore records every completed collection run and exposes it:

curl -s "https://your-server/status/api.php?action=collection_health"

The response carries stale: true once the last run is older than the configured limit - and also when the collector has never run at all, because "no data" is not the same as "all good".

A Cloudflare Worker checks that endpoint every five minutes. It runs outside the monitored host on purpose: a watchdog sharing a machine with the thing it watches dies with it. Point it at a Discord webhook once and it will speak up on its own:

cd apps/worker && npx wrangler secret put WATCHDOG_DISCORD_WEBHOOK

Without that secret the watchdog still checks, but it can only log - and it admits as much on /api/watchdog, rather than looking like it is guarding something.

Agent Registration & Setup

Agents are self-contained telemetry daemons available for Bash, Python, PowerShell, and OpenWrt router systems. Run auto-registration with your server token:

./agent.sh --register --token="YourRegistrationToken" --url="https://monitoring.bloodkings.eu/status/agent_api.php"

Agent Intervals & Remote Actions

Agents run on a configurable cron interval (default: 60 seconds). For OpenWrt routers, opt-in HMAC-signed Remote Actions can be enabled by setting REMOTE_ACTIONS_ENABLED=1 in the agent script.

Agent Troubleshooting

If an agent stops reporting telemetry, verify outgoing HTTPS access to port 443 and check local logs:

# Check systemd agent service logs
journalctl -u bloodkings-agent -n 50 --no-pager