Lumio

A lightweight Rust-based uptime monitoring daemon with Discord webhook notifications.

What is this?

This tool monitors websites and APIs, sending alerts to Discord when they go down or come back up.

Discord Notifications

Your Discord notifications will look like this:

Note: Discord timestamps automatically convert to the viewer's local timezone!

CLI Commands

All commands work both inside and outside Docker. When using Docker, prepend with docker compose exec lumio.

Command	Description
monitor add	Add a new monitor target
monitor remove <name>	Remove a monitor target
monitor list	List all monitor targets
monitor edit <name>	Edit an existing monitor
monitor stats	Show resource usage statistics
monitor test <name> <up|down>	Send a test notification
monitor daemon	Run the monitoring daemon (starts automatically on bootup)

Adding Your First Monitor

monitor add \
  --name example-website \
  --endpoint https://example.com/ \
  --status-range 2xx \
  --interval 60 \
  --webhook https://discord.com/api/webhooks/YOUR_WEBHOOK_URL

CLI Flags Reference

Flag	Required	Default	Description
--name	Yes	-	Unique identifier (auto-converted to lowercase with dashes)
--endpoint	Yes	-	The URL to check
--status-range	Yes	-	What HTTP codes are "good" (2xx, 3xx, or 4xx)
--interval	No	60	How often to check, in seconds (1-360)
--webhook	Yes	-	Your Discord webhook URL
--display-name	No	-	Pretty name for Discord (supports spaces!)
--token	No	-	Bearer token for authenticated APIs
--role-id	No	-	Discord role ID to ping on alerts
--retries	No	3	Failed checks before alerting
--timeout	No	30	Request timeout in seconds
--expected-response	No	-	Response body must contain this to be healthy

Example with Optional Flags

monitor add \
  --name example-api \
  --display-name "Example API" \
  --endpoint https://api.example.com \
  --token "your-bearer-token" \
  --role-id "1254982021261037568" \
  --status-range 2xx \
  --interval 60 \
  --retries 3 \
  --timeout 30 \
  --expected-response "ok" \
  --webhook https://discord.com/api/webhooks/YOUR_WEBHOOK_URL

Managing Monitors

# List all monitors
monitor list

# Edit a monitor (change interval to 120 seconds)
monitor edit example-api --interval 120

# Remove a monitor
monitor remove example-api

# Show system resource usage
monitor stats

# Test Discord notifications (positional arguments, NOT flags)
monitor test example-api up    # Test "operational" message
monitor test example-api down  # Test "unavailable" message

# Get help
monitor help
monitor help add

Deployment

You can deploy this application using the provided Docker Compose file or through Coolify.

Deploy Using Docker Compose

# Clone the codebase
git clone https://github.com/ShadowArcanist/lumio

cd lumio

docker compose up -d
# The daemon runs automatically and starts monitoring your configured endpoints

Deploy Using Coolify

1. Add a new resource in Coolify → "Docker Compose Empty."
2. Paste the contents of the coolify-compose.yaml from the repo into the input field.
3. Click "Deploy!"

Deploy Using Docker

# Build
docker build -t lumio .

# Run daemon
docker run -d \
  -v $(pwd)/data:/data \
  -e LOG_LEVEL=info \
  lumio

# Run CLI command
docker run --rm \
  -v $(pwd)/data:/data \
  lumio list

Configuration

Monitors are stored in /data/config.json. Use the CLI commands (add, edit, remove) to manage monitors.

Example config.json

{
  "monitors": {
    "example-website": {
      "name": "example-website",
      "display_name": "Coolify Cloud API",
      "endpoint": "https://example.com/api/v1/version",
      "bearer_token": "your-secret-token",
      "status_range": "2xx",
      "interval": 60,
      "retries": 3,
      "timeout": 30,
      "webhook_url": "https://discord.com/api/webhooks/...",
      "role_id": "1254982021261037568",
      "expected_response": "ok"
    }
}

Config Field Reference

Field	Required	Type	Description
name	Yes	String	Unique ID (lowercase, no spaces, auto-normalized)
display_name	No	String	Pretty name for Discord (supports spaces and caps)
endpoint	Yes	String	URL to monitor
bearer_token	No	String	Optional authentication token
status_range	Yes	String	Acceptable HTTP codes (2xx, 3xx, or 4xx)
interval	No	Number	Check frequency in seconds (1-360, default: 60)
retries	No	Number	Consecutive failures before alerting (default: 3)
timeout	No	Number	Request timeout in seconds (default: 30)
webhook_url	Yes	String	Discord webhook URL
role_id	No	String	Discord role ID to ping (optional)
expected_response	No	String	Response body must contain this to be healthy

Downtime Tracking

Downtimes are stored in /data/downtime.json. This acts as a temporary database:

• Tracks when downtime started
• Stores failure reason
• Automatically removed after recovery notification is sent
• Persists if the app crashes (prevents duplicate alerts)

Environment Variables

Variable	Default	Description
LOG_LEVEL	info	Log verbosity (error, warn, info, debug, trace)

Common Issues & Solutions

"No such file or directory" error

The app automatically creates missing config files now. If you still see this, ensure the /data directory has proper permissions.

Notifications not sending

• Verify your Discord webhook URL is correct
• Check that the webhook channel still exists
• Use monitor test to verify the webhook works

Monitor not detecting downtime

• Check that --status-range matches your expected status codes
• Verify --retries isn't too high
• Use docker compose logs to see what's happening

Tips for New Users

1. Start simple: Add a monitor with just --name, --endpoint, --status-range, --interval, and --webhook. Add other options later.

2. Use the CLI: All configuration changes should be made via monitor add, monitor edit, and monitor remove commands. Manual edits to config.json are not supported.

3. Test first: After adding a monitor, run monitor test <name> up to verify Discord is working.

4. Use display names: The --display-name flag lets you use pretty names like "Production API" instead of "production-api".

5. Check logs: If something isn't working, check the logs with docker compose logs -f lumio.

6. Bearer tokens: For APIs requiring authentication, use --token "your-token". The app sends it as Authorization: Bearer <token>.

7. Response validation: Use --expected-response to ensure the response body contains expected content.

Health Check

The Docker container includes a health check that runs every 30 seconds to ensure the daemon is running. Check container health with:

docker inspect --format='{{.State.Health.Status}}' lumio

Notes

1. This project was entirely created using AI, but the application has been thoroughly tested.
2. This project was built primarily for my personal use, so I will not be merging pull requests or adding new features unless I need them myself. If you want to make changes or add features, feel free to fork this repository. It’s open-sourced so others can learn from it, use it as a base for their own projects, or even run the application as-is.