Run RackMon in about ten minutes.
RackMon ships as a single container that serves both the API and the web UI. Start on SQLite with zero configuration, move to PostgreSQL when you grow.
1 · Requirements
- A host with Docker (Linux, macOS or Windows). 1 vCPU / 512 MB RAM is plenty to start.
- Outbound network access to the devices you want to poll over SNMP (v2c or v3).
- No account and no internet connection to RackMon is required — the app never phones home.
2 · Quick start
Generate two secrets and run the container. The app refuses to start in production with the insecure defaults, so always set your own.
# pull & run
docker run -d --name rackmon -p 127.0.0.1:8000:8000 \
-e RACKMON_ENVIRONMENT=production \
-e RACKMON_JWT_SECRET=$(openssl rand -hex 32) \
-e RACKMON_MASTER_KEY=$(openssl rand -hex 32) \
-e RACKMON_ADMIN_EMAIL=you@example.com \
-e RACKMON_ADMIN_PASSWORD='a-strong-password' \
-v rackmon_data:/data \
-e RACKMON_DATABASE_URL=sqlite:////data/rackmon.db \
rackmon/rackmon:latestOpen http://localhost:8000 and sign in with the admin email and password you set. The port is bound to 127.0.0.1 on purpose: put RackMon behind a TLS-terminating reverse proxy (Caddy, nginx, Traefik) before anything else can reach it. RACKMON_ENVIRONMENT=production makes it refuse to start on a factory secret rather than warn and carry on.
rackmon_data holds the database at /data. Nothing leaves your server.3 · Add devices
- Simulator (default): RackMon starts with a built-in SNMP simulator so you see live data instantly. Turn it off with
-e RACKMON_POLLER_USE_SIMULATOR=falseto poll real hardware. - Add one device: Devices → Add — enter host, SNMP version and credentials (community for v2c; user/auth/priv for v3).
- Discover a subnet: Discovery scans a range for SNMP hosts and imports what it finds.
4 · Alerts & notifications
Create rules with thresholds, hold windows, dedup and escalation. Deliver to any of:
| Channel | Environment variable |
|---|---|
| Email (SMTP) | RACKMON_SMTP_HOST, RACKMON_SMTP_PORT, RACKMON_SMTP_USER, RACKMON_SMTP_PASSWORD, RACKMON_SMTP_FROM |
| Slack | RACKMON_SLACK_WEBHOOK_URL |
| Microsoft Teams | RACKMON_TEAMS_WEBHOOK_URL |
| Generic webhook | RACKMON_ALERT_WEBHOOK_URL |
| Telegram | RACKMON_TELEGRAM_BOT_TOKEN, RACKMON_TELEGRAM_CHAT_ID |
A missing reading or a maintenance window never fakes an all-clear — RackMon distinguishes "no data" from "recovered".
5 · Single sign-on, LDAP and the status page
These four used to need a paid key. They are now on by default like everything else, so the only thing left is configuring them — which the docs never covered, because they used to just say "buy a licence".
LDAP / Active Directory. Set RACKMON_LDAP_ENABLED=true plus RACKMON_LDAP_SERVER_URI (ldaps://dc.corp.com:636), RACKMON_LDAP_BIND_DN and RACKMON_LDAP_BIND_PASSWORD for the service account that searches, and RACKMON_LDAP_USER_BASE_DN. The defaults for RACKMON_LDAP_USER_FILTER ((uid={username})) and RACKMON_LDAP_EMAIL_ATTR (mail) suit OpenLDAP; for Active Directory use (sAMAccountName={username}). RACKMON_LDAP_ADMIN_GROUP grants admin to members of that group, and RACKMON_LDAP_DEFAULT_ROLE covers everyone else.
OIDC single sign-on. Set RACKMON_OIDC_ENABLED=true, RACKMON_OIDC_ISSUER, RACKMON_OIDC_CLIENT_ID, RACKMON_OIDC_CLIENT_SECRET and RACKMON_OIDC_REDIRECT_URI (point it at <your-url>/api/v1/auth/oidc/callback). The authorization, token and JWKS endpoints are discovered from the issuer unless you override them. ID-token signatures are verified against the provider's JWKS. RACKMON_OIDC_ADMIN_EMAILS is the list that gets admin.
The public status page lives at /status and is read-only and sanitised: it shows state, never hostnames, IPs or readings. White-label branding — name, logo and accent colour — is set in the interface under Settings, not by environment variable.
SLA and availability reports are generated from Reports as PDF, against a target you choose. A device that stopped answering counts as down, not as missing data.
6 · Configuration reference
Every setting is an environment variable prefixed RACKMON_. The most common:
| Variable | Default | What it does |
|---|---|---|
RACKMON_ENVIRONMENT | development | Set to production to enforce the secret-safety checks. |
RACKMON_JWT_SECRET | dev default | Signs session tokens. Set a 32-byte random value. |
RACKMON_MASTER_KEY | dev default | Encrypts stored secrets (SNMP/SMTP) at rest. Set a 32-byte random value. |
RACKMON_DATABASE_URL | local SQLite | e.g. postgresql+psycopg2://user:pass@postgres:5432/rackmon |
RACKMON_ADMIN_EMAIL / RACKMON_ADMIN_PASSWORD | — | The first admin account, created on first boot. |
RACKMON_PUBLIC_BASE_URL | http://localhost:8000 | The URL users reach the app at (used in links/emails). |
RACKMON_LICENSE_KEY | empty | Read and ignored since 1.3.0. Kept so an old .env still starts. |
RACKMON_POLLER_USE_SIMULATOR | true | Set false to poll real SNMP hardware. |
RACKMON_SEED_DEMO_DATA | true | Set false for a clean, empty install. |
LDAP, OIDC, SNMP traps and the scheduled weekly report have their own RACKMON_LDAP_*, RACKMON_OIDC_*, RACKMON_SNMP_TRAP_* and RACKMON_REPORT_WEEKLY_* variables. Every one of them, with its default and a comment, is in .env.example and in config.py, which is the file they are read from.
7 · Back up & upgrade
- Backup: back up the
/datavolume (or your PostgreSQL database). That is all your state. - Upgrade:
docker pull rackmon/rackmon:latest, then recreate the container with the same env and volume. Your data carries over: new columns are added on start, so no manual migration step. Check the past advisories before skipping several versions.