NAME

beacon

A self-hosted uptime monitor that keeps track of your websites and services.

★ 5 · last pushed 2026-11-04

DESCRIPTION

Beacon is a self-hosted uptime monitor for your websites and services. The URL scheme picks the check type: http and https run an HTTP GET, tcp checks a plain port, and ssl validates a TLS certificate.

Response times are tracked for every check, and a notification system alerts subscribers on downtime. https monitors follow certificate expiry automatically and turn degraded 30 days before expiry, with a daily reminder until it is renewed.

Incidents live as YAML files in a git repository, and everything is stored in SQLite for easy deployment. Configuration comes from a YAML file or from environment variables.

FEATURES

HTTP and HTTPS endpoint monitoring with response time tracking
TCP port monitoring
TLS certificate expiry monitoring with warnings 30 days ahead
Notification system for downtime alerts
Incident management with git-based storage
Web dashboard
SQLite database and Docker-ready deployment
Automatic cleanup of old data

QUICK START

Docker

docker run -d \
   -p 3000:3000 \
   -v $(pwd)/data:/data \
   -e BEACON_CONFIG=/data/config.yaml \
   ghcr.io/mizuchilabs/beacon:latest

Docker Compose

services:
  beacon:
    image: ghcr.io/mizuchilabs/beacon:latest
    container_name: beacon
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
      - ./config.yaml:/config.yaml:ro
    environment:
      - BEACON_CONFIG=/config.yaml
      - BEACON_RETENTION_DAYS=90
      - BEACON_TITLE=My Status Page
      - TZ=America/New_York
    restart: unless-stopped

CLI

beacon --config config.yaml

CONFIGURATION

Name	Description
BEACON_PORT	Server port. Default: 3000.
BEACON_CONFIG	Path to the monitors configuration file. Also --config. Default: config.yaml.
BEACON_MONITORS	YAML configuration as a string, alternative to a file.
BEACON_TIMEOUT	Check timeout for HTTP requests, TCP dials, and TLS handshakes. Default: 30s.
BEACON_RETENTION_DAYS	Days to keep raw checks. Default: 30.
BEACON_TIMEZONE	Display timezone. Default: Europe/Vienna.
BEACON_TRUSTED_PROXIES	Client IP source for rate limiting. Default: direct.
BEACON_INCIDENT_REPO	Git repository URL for incident files.

LINKS

[github]https://github.com/mizuchilabs/beacon

SELF-HOSTED VS COMMERCIAL

Self-hosting beacon is free under the Apache-2.0 license. Run it on your own iron. Commercial licensing, support, and managed offerings for businesses are on the business page.