Prepare public release docs
This commit is contained in:
Stanislav Rossovskii
177
README.md
177
README.md
@@ -1,62 +1,149 @@
|
||||
English | [Русский](README.ru.md)
|
||||
|
||||
# Monlet
|
||||
|
||||
Monlet is a lightweight event and check monitoring system.
|
||||
Monlet 0.1.0 is a small self-hosted monitoring system for local checks, host
|
||||
heartbeats, incidents, and notification delivery state.
|
||||
|
||||
It is split into three independent applications:
|
||||
|
||||
|
||||
- `agent/` - a small Go binary installed on monitored hosts.
|
||||
- `server/` - a Python/FastAPI backend that owns inventory, state, incidents, and notifications.
|
||||
- `web/` - a Next.js dashboard with agent admission controls.
|
||||
Monlet is built for the gap between ad-hoc shell checks and a full observability
|
||||
platform. Agents run checks on the hosts where the facts live, push only
|
||||
structured observations to the server, and leave incident and notification
|
||||
lifecycle decisions to one central backend.
|
||||
|
||||
All three applications are implemented and run together via Docker Compose. The current release covers agent ingestion with operator admission, server-owned incident lifecycle and notifier outbox, a Next.js dashboard, and partitioned event retention.
|
||||
## Why Monlet?
|
||||
|
||||
## Scope
|
||||
Simple infrastructure often starts with cron jobs, shell probes, and a chat
|
||||
webhook. That works until you need to answer basic operational questions:
|
||||
|
||||
Monlet v1 focuses on local checks, central state, and simple visibility:
|
||||
- Which hosts are alive, stale, or dead?
|
||||
- Which local checks are currently degraded?
|
||||
- Did this failure open an incident, resolve one, or get deduplicated?
|
||||
- Were notifications sent, retried, or failed?
|
||||
- Can agents survive a server outage without creating duplicate events?
|
||||
|
||||
- agents run local checks from TOML config;
|
||||
- agents expose Prometheus metrics and/or push facts to the server;
|
||||
- server ingests heartbeats and check events idempotently;
|
||||
- server owns current state, incident lifecycle, and notifier retries;
|
||||
- web UI reads server APIs and does not mutate state.
|
||||
Monlet keeps that model explicit without adding remote command execution,
|
||||
remote config push, or a heavyweight incident-management platform.
|
||||
|
||||
## Non-goals for v1
|
||||
## What It Does
|
||||
|
||||
- remote command execution;
|
||||
- remote config push;
|
||||
- full RBAC;
|
||||
- multi-tenant enterprise model;
|
||||
- complex silences or inhibition engine;
|
||||
- Grafana replacement;
|
||||
- long-term log storage;
|
||||
- full incident management platform;
|
||||
- Kubernetes operator;
|
||||
- plugin marketplace;
|
||||
- distributed server cluster.
|
||||
- A Go agent runs configured local commands from TOML.
|
||||
- Agents send heartbeats and check events to the server over the `/api/v1` API.
|
||||
- The FastAPI server owns inventory, current check state, incidents, retention,
|
||||
and notifier outbox retries.
|
||||
- The Next.js UI shows agents, checks, incidents, events, and notification
|
||||
delivery state.
|
||||
- Operator admission is required before a new agent key can affect monitoring
|
||||
state.
|
||||
- Server and agents expose Prometheus metrics for the monitoring system itself.
|
||||
|
||||
## Repository Map
|
||||
## Screenshots
|
||||
|
||||
- `docs/` - architecture, ADRs, development, and operations docs.
|
||||
- `plan/` - stage workflow and exit checkpoints.
|
||||
- `api/` - versioned OpenAPI contract.
|
||||
- `agent/` - Go agent: scheduler, runner, spool, metrics.
|
||||
- `server/` - Python/FastAPI backend: ingestion, detector, notifier outbox.
|
||||
- `web/` - Next.js dashboard and agent admission UI.
|
||||
- `deploy/` - local and observability deployment examples.
|
||||
- `examples/` - example checks and configs.
|
||||
Agents and admission state:
|
||||
|
||||
## Start Here
|
||||
|
||||
|
||||
Read in this order:
|
||||
Current check states:
|
||||
|
||||
1. `docs/README.md`
|
||||
2. `docs/architecture/overview.md`
|
||||
3. `ROADMAP.md`
|
||||
4. `TODO.md`
|
||||
5. `plan/README.md`
|
||||
6. `AGENTS.md`
|
||||
7. `CLAUDE.md`
|
||||
|
||||
|
||||
## Current Status
|
||||
Open and resolved incidents:
|
||||
|
||||
Active development. Stages 0–6 are implemented. Run the stack via `docker compose up --build` from `deploy/`. See `docs/operations/deployment.md` and `docs/ops/` runbooks.
|
||||
|
||||
|
||||
Notifier outbox state:
|
||||
|
||||
|
||||
|
||||
## Features in 0.1.0
|
||||
|
||||
- Local command checks with `ok`, `warning`, `critical`, and `unknown` states.
|
||||
- Heartbeat-based agent liveness with alive, stale, and dead status.
|
||||
- Durable on-disk agent spool for server outages.
|
||||
- Idempotent event ingestion and duplicate-safe replay.
|
||||
- Server-owned incident open/resolve lifecycle.
|
||||
- Notification outbox with retry and failure state.
|
||||
- Debug, webhook, Telegram, and Alertmanager notifier implementations.
|
||||
- Agent admission and blacklist controls.
|
||||
- Partitioned PostgreSQL event storage and bounded retention.
|
||||
- Docker Compose local stack and showcase stand.
|
||||
- Prometheus metrics for server and agent runtime behavior.
|
||||
|
||||
## Quick Start
|
||||
|
||||
Run the local stack:
|
||||
|
||||
```sh
|
||||
cd deploy
|
||||
MONLET_AUTH_TOKEN=$(openssl rand -hex 16) docker compose up --build
|
||||
```
|
||||
|
||||
Services:
|
||||
|
||||
- Web UI: <http://127.0.0.1:3000>
|
||||
- Server API: <http://127.0.0.1:8000>
|
||||
- Readiness: <http://127.0.0.1:8000/api/v1/ready>
|
||||
- Metrics: <http://127.0.0.1:8000/metrics>
|
||||
|
||||
Run the full demo stand:
|
||||
|
||||
```sh
|
||||
SHOWCASE_KEEP=1 bash deploy/e2e-showcase.sh
|
||||
```
|
||||
|
||||
The showcase starts PostgreSQL, the server, the web UI, a mock webhook, and
|
||||
several demo agents. It drives mixed check states, liveness transitions,
|
||||
resolved incidents, notifier retries/failures, and spool replay.
|
||||
|
||||
## Architecture
|
||||
|
||||
Monlet is a monorepo with three independent applications:
|
||||
|
||||
- `agent/` - Go binary installed on monitored hosts.
|
||||
- `server/` - Python/FastAPI backend with PostgreSQL storage.
|
||||
- `web/` - Next.js operator dashboard.
|
||||
|
||||
The server owns incident and notification lifecycle. The agent sends facts only.
|
||||
The web UI is read-only for monitoring state; agent admission and blacklist
|
||||
controls are the v1 mutation surface.
|
||||
|
||||
Public API contracts live in `api/openapi.yaml`. Design and operations docs live
|
||||
under `docs/`.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
Monlet 0.1.0 is intentionally not:
|
||||
|
||||
- a remote command runner;
|
||||
- a remote config-push system;
|
||||
- a Grafana replacement;
|
||||
- a full incident-management platform;
|
||||
- a multi-tenant RBAC product;
|
||||
- a Kubernetes operator;
|
||||
- a distributed server cluster.
|
||||
|
||||
## Development
|
||||
|
||||
Start with:
|
||||
|
||||
1. `deploy/README.md`
|
||||
2. `agent/README.md`
|
||||
3. `server/README.md`
|
||||
4. `web/README.md`
|
||||
5. `api/README.md`
|
||||
|
||||
Dependency caches and virtual environments are kept inside the repository. See
|
||||
the component READMEs for current local development commands.
|
||||
|
||||
## Status
|
||||
|
||||
Monlet is active early-stage software. The 0.1.0 release is usable for local
|
||||
development, demos, and controlled internal deployments. Internal contracts may
|
||||
still change while the public API remains versioned under `/api/v1`.
|
||||
|
||||
`0.1.0` is the product release version. `/api/v1` is the API namespace.
|
||||
|
||||
## License
|
||||
|
||||
MIT.
|
||||
|
||||
Reference in New Issue
Block a user