mirror of
https://github.com/Dvorinka/beszel.git
synced 2026-06-03 21:02:56 +00:00
Tomas Dvorak
8011d487f1
- Add status pages, incidents, badges, maintenance, bulk ops, and metrics - Add Docker packaging, env example, and frontend routes - Refresh GitHub workflows and project metadata
169 lines
4.5 KiB
Markdown
169 lines
4.5 KiB
Markdown
# Beszel - Unified Monitoring Platform
|
|
|
|
> Lightweight server monitoring, website monitoring, and domain expiry tracking in a single dashboard.
|
|
|
|
Beszel is a unified monitoring platform that combines system metrics, service uptime monitoring, and domain/SSL expiry tracking. Built on [PocketBase](https://pocketbase.io/) with a modern React frontend, it is designed to be lightweight, self-hosted, and production-ready.
|
|
|
|
## Quick Start
|
|
|
|
### Docker Compose
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/henrygd/beszel.git
|
|
cd beszel
|
|
|
|
# Copy and edit environment variables (optional)
|
|
cp .env.example .env
|
|
|
|
# Start the hub
|
|
make start
|
|
# or: docker compose up -d
|
|
|
|
# View logs
|
|
make logs
|
|
|
|
# Stop everything
|
|
make stop
|
|
```
|
|
|
|
The hub will be available at `http://localhost:8090`. Create your admin account on first visit.
|
|
|
|
Agents run on separate hosts and connect to the hub. See [Adding Agents](#adding-agents) below.
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `APP_URL` | `http://localhost:8090` | Public URL for links |
|
|
| `INSTANCE_NAME` | `Beszel Monitoring` | Instance display name |
|
|
| `REGISTRATION_ENABLED` | `true` | Allow new user registration |
|
|
| `MAX_MONITORS_PER_USER` | `50` | Monitor limit per user |
|
|
| `MAX_DOMAINS_PER_USER` | `50` | Domain limit per user |
|
|
| `MAX_STATUS_PAGES` | `10` | Status page limit |
|
|
| `TWO_FACTOR_ENABLED` | `true` | Enable 2FA |
|
|
| `PASSKEY_ENABLED` | `true` | Enable passkey auth |
|
|
| `STATUS_PAGES_ENABLED` | `true` | Enable public status pages |
|
|
| `BADGES_ENABLED` | `true` | Enable SVG badge generation |
|
|
| `PAGESPEED_ENABLED` | `true` | Enable PageSpeed checks |
|
|
| `SUBDOMAIN_DISCOVERY` | `true` | Auto-discover subdomains |
|
|
|
|
## Features
|
|
|
|
### System Monitoring
|
|
- CPU, memory, disk, network metrics with historical charts
|
|
- Docker / Podman container stats
|
|
- GPU monitoring (Nvidia, AMD, Intel)
|
|
- Temperature sensors and battery status
|
|
- S.M.A.R.T. disk health tracking
|
|
|
|
### Website & Service Monitoring
|
|
- HTTP/HTTPS, TCP, Ping, DNS checks
|
|
- Keyword and JSON query validation
|
|
- Response time tracking with Recharts visualizations
|
|
- Uptime statistics (24h / 7d / 30d)
|
|
- Maintenance windows with alert suppression
|
|
|
|
### Domain Monitoring
|
|
- WHOIS lookup with RDAP + TCP fallback (works in scratch containers)
|
|
- SSL certificate expiry tracking
|
|
- DNS records (NS, MX, TXT)
|
|
- Subdomain auto-discovery (50 common subdomains)
|
|
- Registrar, host geolocation, and IP info
|
|
- Bulk CSV import / JSON export
|
|
|
|
### Platform
|
|
- Multi-user with role-based access
|
|
- OAuth 2.0 / OIDC support
|
|
- Public status pages with custom CSS
|
|
- Incident management with acknowledge/resolve workflow
|
|
- Calendar view for expiry dates and incidents
|
|
- Prometheus metrics export (`/metrics`)
|
|
- SVG status badges for embedding
|
|
- Browser push notifications + PWA support
|
|
- PageSpeed Insights / Lighthouse integration
|
|
- Automatic backups to disk or S3
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Hub (Go + PocketBase + React)
|
|
- Web UI (port 8090)
|
|
- REST API + WebSocket
|
|
- SQLite database with migrations
|
|
- Scheduled jobs (domain checks, heartbeat cleanup)
|
|
|
|
Agent (Go)
|
|
- Runs on monitored hosts
|
|
- Collects system + Docker metrics
|
|
- Connects to hub via SSH tunnel
|
|
```
|
|
|
|
## Adding Agents
|
|
|
|
Agents run on the hosts you want to monitor and connect back to the hub via SSH.
|
|
|
|
### On a remote host
|
|
|
|
```bash
|
|
# Build the agent binary
|
|
make build-agent
|
|
|
|
# Copy the binary to the remote host
|
|
# Set KEY to the public key from the hub UI (Settings > Add System)
|
|
KEY="ssh-ed25519 ..." ./beszel-agent
|
|
```
|
|
|
|
### With Docker on a remote host
|
|
|
|
```bash
|
|
# Build the agent image
|
|
make docker-agent
|
|
|
|
# Run the agent container
|
|
docker run -d \
|
|
--name beszel-agent \
|
|
--pid host \
|
|
-e KEY="ssh-ed25519 ..." \
|
|
-v /var/run/docker.sock:/var/run/docker.sock:ro \
|
|
-p 45876:45876 \
|
|
beszel-agent:latest
|
|
```
|
|
|
|
## Building
|
|
|
|
```bash
|
|
# Build hub + agent binaries
|
|
make build
|
|
|
|
# Build with Docker
|
|
make docker-hub
|
|
make docker-agent
|
|
|
|
# Development mode
|
|
make dev
|
|
```
|
|
|
|
## API
|
|
|
|
Protected endpoints require Bearer token authentication.
|
|
|
|
| Endpoint | Description |
|
|
|----------|-------------|
|
|
| `GET /api/beszel/monitors` | List monitors |
|
|
| `GET /api/beszel/domains` | List domains |
|
|
| `GET /api/beszel/status-pages` | List status pages |
|
|
| `GET /api/beszel/incidents` | List incidents |
|
|
| `GET /api/beszel/maintenance` | List maintenance windows |
|
|
| `GET /metrics` | Prometheus metrics (public) |
|
|
| `GET /status/:slug` | Public status page |
|
|
| `GET /badge/:type/:id.svg` | Status badge (public) |
|
|
|
|
## Credits
|
|
|
|
Based on **[Beszel](https://github.com/henrygd/beszel)** by [henrygd](https://github.com/henrygd).
|
|
|
|
## License
|
|
|
|
MIT License. See [LICENSE](LICENSE).
|