Skip to content

Getting Started

Jump to bottom
X4Applegate edited this page Apr 14, 2026 · 1 revision

Getting Started

Prerequisites

  • Docker and Docker Compose
  • A MariaDB (or MySQL 8.0+) instance — included in the example Compose file
  • NET_RAW Linux capability on the container (required for ICMP ping checks)
  • A reverse proxy (Caddy, nginx, Traefik) for HTTPS — strongly recommended for production

Quick Start

1. Clone the repository

git clone https://github.com/X4Applegate/status-server.git
cd status-server

2. Copy the example Compose file

cp docker-compose.example.yml docker-compose.yml

3. Set required environment variables

Edit docker-compose.yml and fill in the required values:

environment:
  - DB_HOST=mariadb
  - DB_USER=statusadmin
  - DB_PASSWORD=your_secure_password       # change this
  - DB_NAME=status_monitor
  - SESSION_SECRET=a_long_random_string    # change this — app refuses to start if left as default
  - EXTERNAL_URL=https://status.example.com
  - TZ=America/Los_Angeles

The app will refuse to start in production if SESSION_SECRET is still the default value or DB_PASSWORD is unset.

4. Start the stack

docker compose up -d

The app will be available at http://localhost:3000 (or your configured port). On first run, all database tables are created automatically.

First-Time Setup

On your first visit to the app, you will be presented with a setup wizard to create the initial admin account. Fill in a username and password — this account has full admin access.

After setup, log in at /login to access the admin panel.

Reverse Proxy (Caddy)

Caddy is the recommended reverse proxy for automatic HTTPS:

status.example.com {
    reverse_proxy status-server:3000
}

For custom per-dashboard domains (see Multi-Tenant / Groups), add additional blocks:

status.acmecorp.com {
    reverse_proxy status-server:3000
}

The app detects the Host header and serves the correct branded dashboard automatically.

Health Check Endpoint

The app exposes /healthz for Docker health checks and orchestration platforms:

GET /healthz
→ 200 OK  {"status":"ok"}

This is already wired up in the example Compose file.

Next Steps

Clone this wiki locally