Skip to content

Configuration

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

Configuration

Environment Variables

Required

Variable Description
DB_HOST MariaDB hostname (e.g. mariadb in Docker Compose)
DB_USER Database username
DB_PASSWORD Database password
DB_NAME Database name (tables are auto-created on first run)
SESSION_SECRET Random string for session signing — must be changed from default or the app will refuse to start in production

Optional — Application

Variable Default Description
PORT 3000 HTTP listen port
DB_PORT 3306 MariaDB port
EXTERNAL_URL — Base URL used in webhook dashboard links when no custom domain is set (e.g. https://status.example.com)
TZ UTC Container timezone (e.g. America/Los_Angeles)
NODE_ENV production (in Docker) Set to development for pretty-printed logs
LOG_LEVEL info Pino log level: debug, info, warn, error
CHECK_INTERVAL 30000 Global health check poll interval in milliseconds
CONFIG_PATH /config/servers.json Path to legacy servers.json for one-time migration to the database

Optional — Branding / Legal

Variable Default Description
APP_OWNER Richard Applegate Owner name shown on Privacy Policy and Terms pages
APP_CONTACT_EMAIL admin@richardapplegate.io Contact email shown on legal pages
APP_HOME_URL / URL that the Home button in the admin panel links to

SMTP Email (for webhook alerts)

SMTP settings can be configured two ways:

Option A — Admin Settings tab (recommended) Log into the admin panel → Settings tab → fill in SMTP fields. Changes take effect immediately with no restart needed.

Option B — Environment variables

Variable Description
SMTP_HOST Mail server hostname
SMTP_PORT SMTP port (typically 587 for STARTTLS)
SMTP_USER Authentication username
SMTP_PASS Authentication password
SMTP_FROM Sender address (e.g. alerts@example.com)

Google OAuth

Google OAuth lets users sign in with their Google account instead of a local password.

  1. Create a project in Google Cloud Console and set up an OAuth 2.0 client ID.
  2. Set the authorized redirect URI to https://your-domain.com/auth/google/callback.
  3. In the admin panel → Settings tab, enter your Client ID and Client Secret.
  4. Optionally set GOOGLE_CALLBACK_URL as an environment variable if your callback URL differs from {EXTERNAL_URL}/auth/google/callback.

Cloudflare Turnstile CAPTCHA

Turnstile adds a privacy-friendly CAPTCHA to the login page — a good defense against brute-force attacks.

  1. Create a Turnstile widget at Cloudflare Dashboard → Turnstile.
  2. In the admin panel → Settings tab, enter your Site Key and Secret Key.
  3. The CAPTCHA widget appears on the login page immediately. It is automatically skipped on the first-time setup wizard.

Boot-Time Validation

In NODE_ENV=production, the app will refuse to start if:

  • SESSION_SECRET is still the default value
  • DB_PASSWORD is unset or empty

These checks prevent accidental deployment with insecure defaults.

Persistent Sessions

Sessions are stored in the sessions MariaDB table via express-mysql-session. This means:

  • Sessions survive container restarts and re-deploys
  • No external Redis or Memcached needed
  • Sessions are cleaned up automatically when they expire

Legacy Migration (servers.json)

If you are upgrading from an older version that used a flat servers.json file:

  1. Set CONFIG_PATH to the path of the file (default: /config/servers.json).
  2. On startup, if the status_servers table is empty and the file exists, servers are imported automatically.
  3. After migration, the file is not re-read — data lives in the database.

Clone this wiki locally