Skip to content

Latest commit

 

History

History
265 lines (192 loc) · 9.27 KB

README.md

File metadata and controls

265 lines (192 loc) · 9.27 KB

Beacon

Beacon

Monitor your websites and periodic jobs with ease.

Beacon tracks the health of your websites, servers, and applications, so you know that everything runs as it should.

You can use Beacon to:

  • Automatically check website availability and content.
  • Receive notifications when services fail to send updates (heartbeats).
  • Get periodic health reports via email or web GUI.

There are two main ways to use Beacon:

  • Beacon checks your website or server for expected response = "web service".
  • You sends health information (heartbeats) to Beacon = "heartbeat service".

Beacon aims to be flexible and lets you choose how to use it.

🚀 Quickstart

Beacon can be easily installed anywhere Go is available.

  1. Install Beacon
go install github.com/davidmasek/beacon@latest
  1. Start the Server
# start server
beacon start --config config.sample.yaml
  1. Monitor Your Services
  • Website Monitoring: Use the configuration file to specify URLs for automatic periodic checks.
  • Heartbeat Monitoring: Send periodic health updates (heartbeats) from your applications.
  1. Check the Status

Docker

Beacon is also available as a Docker container. compose.yaml provides an example of using it with Docker Compose and latest image available from Docker Hub.

docker compose up

🔧 Configuration

Beacon uses a configuration file to define monitored services and email settings for notifications. The default location is ~/beacon.yaml, but you can specify a custom location using the --config CLI flag. If no configuration file is found, Beacon will create a default one.

Examples

Websites. Verify that your homepage is accessible.

services:
  my-homepage:
    url: "https://example.com/"

APIs. Verify that your API is accessible and returning expected content.

services:
  my-api:
    url: "https://api.example.com/health"
    status: [200]
    content: ["healthy"]

Periodic Jobs. Ensure your cron jobs or other recurring tasks are running by sending a heartbeat after each run.

services:
  nightly-backup:

Service configuration

Services are defined in the services section of the config file. Each service must have a unique name.

Web services: Specify a url to periodically check the service.

services:
  beacon-github:
    url: "https://github.com/davidmasek/beacon"

Heartbeat services: Specify only the service name.

Note that the line still ends with colon :, to ensure it is valid YAML file.

services:
  my-app:

Additional Options

You can customize service behavior with optional fields.

Field Description Default
timeout Time (with units, e.g., 24h, 48h) after which a service is considered unhealthy. 24h
enabled Set to false to temporarily disable monitoring for this service. true
status HTTP status codes that indicate the service is healthy. 200
content Expected content in the response body (all values specified must be present). No checks

The option timeout determines how long to consider a service healthy after a successful health check. It defaults to 24h and needs to be specified with the unit included (6h, 24h, 48h, ...). For example, if a service has a timeout of 24 hours, it will be considered failed if it does not receive heartbeat for 24 hours.

timeout does not override health checks. For example if your website responds with unexpected status code (e.g. 404, 5xx, depending on settings) it will be immediately considered failed even if the timeout period did not pass yet.

Email configuration

Email notifications are optional but recommended for receiving health reports. Configure the email section in the config file with your SMTP server details. You can find many SMTP providers online, both paid and free.

Field Description Required Example
smtp_server Address of the SMTP server Yes smtp.gmail.com
smtp_port SMTP port Yes 587
smtp_username SMTP server username Yes [email protected]
smtp_password SMTP server password Yes your-password
send_to Recipient email address Yes [email protected]
sender Email address used as the sender Yes [email protected]
prefix String prepended to email subject for easy filtering No [Production]

Example:

email:
  smtp_server: "smtp.gmail.com"
  smtp_port: 587
  smtp_username: "[email protected]"
  smtp_password: "your-password"
  send_to: "[email protected]"
  sender: "[email protected]"
  prefix: "[Production]"

You can use environment variables instead. For example:

export BEACON_SMTP_PASSWORD="your-password"

Configuration sources

Beacon supports multiple configuration sources, with the following priority (highest to lowest):

  1. CLI Flags (e.g., --config)
  2. Environment Variables (e.g., BEACON_SMTP_PASSWORD)
  3. Configuration File (default: ~/beacon.yaml)

Environment variables use the prefix BEACON_ and replace dots (.) with underscores (_). For example, to override the smtp_port field in the email section:

export BEACON_EMAIL_SMTP_PORT=465

API

Beacon provides an HTTP API to interact with your monitored services. You can use the API to send heartbeats, retrieve service statuses, and integrate Beacon into your workflows.

Available endpoints

Endpoint Method Description
/services/<id>/beat POST Send a heartbeat for a specific service.
/services/<id>/status GET Retrieve the latest health status of a service.

Examples

Send a Heartbeat:

curl -X POST http://localhost:8088/services/my-service-name/beat

Response:

{
  "service_id": "my-service-name",
  "timestamp": "2025-01-11T17:20:09Z"
}

Get Service Status:

curl -X GET http://localhost:8088/services/my-service-name/status

Response:

{
  "service_id": "my-service-name",
  "timestamp": "2025-01-11T17:20:09Z"
}

Checking service status

Beacon will automatically send you reports about your services. You can always check current status of your services on the web GUI, by default on http://localhost:8088.

You can also check status of a specific service with the HTTP API or generate the full report via CLI. This enables you to build your own logic and reporting on top of Beacon as needed.

# view current status in your browser (default address)
http://localhost:8088

# use HTTP API (curl as an example, use anything you want)
curl http://localhost:8088/services/my-service-name/status

# generate report for all your services
beacon report
# generate report and send it via email
# (see below for email configuration)
beacon report --send-mail

Database

Beacon uses beacon.db file inside your home directory to store it's data.

You can specify different path using the BEACON_DB env variable.

If using Docker, mount the database file to persist data between container restarts.

🌟 Beacon status

Beacon is just starting and some things may be under construction 🚧, or not even that (= some features currently available only in your imagination 💭).

If you want to use Beacon you currently have to run, host and potentially (gasp) debug it yourself (although I do offer help if needed). A publicly available running instance is planned, so you don't have to do it all.

Development notes and more detailed status is available in README-dev.

⚙️ Build

# build a single binary called `beacon`
go build

🔬 Test

The Go tests are intended as the main testing component. They should run fast so you can iterate quickly during development. They should cover main functionality (server, CLI, reporting, ...), including reasonable fail scenarios (incorrect requests, config, ...).

Run Go tests:

go test ./...
# verbose mode
go test -v ./...
# disable cache
go test -count=1 ./...

Additionally there is a test script for Docker. This script has two goals. First, it tests that the Docker image can be build and starts correctly, ensuring people can use Beacon via Docker. Second, it runs Beacon in a clean environment, which helps catch problems that might be hidden during local development.

The test_docker.sh script also tests sending email. For this, valid SMTP configuration is required. See the script source if you are interested in running it.

Run testing script for Docker:

./test_docker.sh