Servicarr

Live Demo: https://status.jenodoescode.com

A lightweight, self-hosted status page that monitors your services and displays real-time uptime. Built with Go and vanilla JavaScript, deployed via Docker.

• Service Monitoring — HTTP, TCP, DNS and "always up" health checks with configurable per-service intervals and timeouts
• Service Relationships — Define depends_on (hierarchical) and connected_to (peer) relationships with visual matrix view
• Setup Wizard — First-run wizard to configure credentials, add services and optionally import a database backup
• 20+ Service Templates — Pre-built templates for Plex, Sonarr, Radarr, Jellyfin, Nextcloud, Home Assistant, Pi-hole and more
• Uptime Bars — 30-day visual uptime history per service with daily granularity; click any day for hour-by-hour breakdown
• Matrix View — Network topology visualisation with dependency arcs, connected-to links and status lines
• System Resources — Live CPU, RAM, disk, GPU, swap, network, containers, processes and uptime via Glances
• Multi-Channel Alerts — SMTP, webhook, Discord, Telegram, Gotify, Pushover, ntfy and Apprise notifications
• Status Alerts — Public maintenance/incident banners
• Admin Panel — Manage services, view logs, reorder cards, toggle monitoring, import/export database
• Security — CSRF protection, CSP headers (no unsafe-inline for scripts), HSTS, IP-based rate limiting, auto-blocking after failed logins, IP whitelist/blacklist, SSRF protection, request body size limits
• Responsive — Mobile-optimised layout with touch-friendly uptime tooltips
• Logging — Structured internal logs (info/warn/error) with search, filtering and auto-pruning
• Docker Ready — Multi-stage build, non-root container, SQLite storage

• Docker and Docker Compose
• Or: Go 1.25+ for local development

1. Clone the repository

   git clone https://github.com/JeKaQM/Servicarr_.git
   cd Servicarr_

2. Create a .env file in the project root (optional — the setup wizard handles most settings):

   PORT=4555
   UNBLOCK_TOKEN=<a-secure-random-string>

3. Start the application

   docker compose -f deploy/docker-compose.yml up -d

4. Open http://localhost:4555 — the setup wizard will guide you through first-time configuration.

1. Run the application

   go run ./app

2. Open http://localhost:4555

All settings are stored in SQLite after the setup wizard completes. The following environment variables can still be set:

Production deployment: Always run behind a reverse proxy (nginx, Caddy, Cloudflare Tunnel) that terminates TLS. The application sets Strict-Transport-Security, X-Frame-Options: DENY, and strict CSP headers automatically.

Set during the setup wizard. Defaults if using env-based config:

• Username: admin
• Password: Set via ADMIN_PASSWORD env var

• Rate limiting: Login 10/min, public API 120/min, health-check 30/min, setup/unblock 5/min per IP
• Auto-blocking: 3 failed login attempts → 24-hour IP block (cleared on successful login)
• IP whitelist / blacklist: Managed from the admin panel
• CSRF tokens: Double-submit cookie pattern on all state-changing requests
• Session auth: HMAC-SHA256 signed cookies with HttpOnly, SameSite=Lax, Secure flags; crypto/rand generated secret
• CSP headers: Strict Content-Security-Policy (no unsafe-inline for scripts)
• HSTS: Strict-Transport-Security header on all responses
• SSRF protection: Cloud metadata endpoints (169.254.169.254, metadata.google.internal) blocked in health-check URLs
• Request limits: 35 MB global body size limit; minimum 8-character passwords
• Slowloris protection: ReadHeaderTimeout set on the HTTP server
• Graceful shutdown: SIGINT/SIGTERM signal handling with connection draining
• SQLite hardening: WAL mode, busy timeout, single-connection pool
• Non-root container: Docker image runs as unprivileged servicarr user; port bound to 127.0.0.1
• Self-unblock: POST /api/self-unblock with {"token": "<UNBLOCK_TOKEN>"} to remove your own IP block

Servicarr_/
├── app/
│   ├── main.go                 # Entry point, scheduler, server
│   └── internal/
│       ├── alerts/             # SMTP email alerting
│       ├── auth/               # Session / HMAC auth
│       ├── cache/              # TTL in-memory cache
│       ├── checker/            # HTTP / TCP / DNS health checks
│       ├── config/             # Env-based configuration
│       ├── database/           # SQLite schema + CRUD
│       ├── handlers/           # HTTP handlers + routes
│       ├── models/             # Data structures
│       ├── monitor/            # Consecutive-failure tracker
│       ├── ratelimit/          # Token-bucket rate limiter
│       ├── resources/          # Glances API v4 client
│       ├── security/           # IP blocking, CSP, middleware
│       └── stats/              # Heartbeat recording + aggregation
├── web/
│   ├── static/                 # CSS, JS, images
│   └── templates/              # Go HTML templates
├── deploy/
│   ├── Dockerfile              # Multi-stage Go → Debian slim
│   └── docker-compose.yml      # Production compose file
├── go.mod
└── README.md

docker build -f deploy/Dockerfile -t servicarr:latest .

go test ./...

Test suites cover 6 packages (76 tests): auth, cache, checker, monitor, ratelimit, security.

App won't start?

• Check your .env file exists or environment variables are set
• Ensure port 4555 is not in use: lsof -i :4555
• Check container logs: docker logs servicarr

Services show as down?

• Verify service URLs are correct and reachable from inside the container
• For *arr apps and services behind API keys, set the API token in the service config
• Check firewall and Docker network connectivity

Resources section shows UNAVAILABLE?

• Ensure Glances is running and accessible from the container
• Configure the Glances host:port in Admin → Resources
• Check that Glances API v4 is enabled (default port 61208)

Login not working?

• Clear browser cookies and retry
• If your IP is blocked, use the self-unblock endpoint with your UNBLOCK_TOKEN
• Blocked IPs are stored in the database and persist across restarts

Uptime bars are all grey?

• This is normal on a fresh install — data accumulates once the scheduler runs
• Wait a few minutes for the first data points to appear
• Verify ENABLE_SCHEDULER=true (default)

MIT

Created by jekaq