[English](README.md) | Русский

# Monlet

Monlet 0.1.0 - небольшой self-hosted мониторинг для локальных проверок,
heartbeat-состояния хостов, инцидентов и доставки уведомлений.

![Панель агентов Monlet](docs/assets/readme/agents.png)

Monlet закрывает промежуток между набором shell-проверок и полноценной
observability-платформой. Агенты запускают проверки там, где живут факты,
отправляют на сервер только структурированные наблюдения, а жизненный цикл
инцидентов и уведомлений остаётся в одном центральном backend.

## Зачем Monlet?

Простая инфраструктура часто начинается с cron-задач, shell-проб и webhook в
чат. Это работает, пока не нужно быстро ответить на базовые операционные
вопросы:

- какие хосты alive, stale или dead;
- какие локальные проверки сейчас degraded;
- открылся ли инцидент, закрылся ли он или событие было deduplicated;
- ушло ли уведомление, попало ли в retry или failed;
- переживут ли агенты outage сервера без дублей событий.

Monlet делает эту модель явной, но не добавляет remote command execution,
remote config push или тяжёлую incident-management платформу.

## Что он делает

- Go agent запускает локальные команды из TOML-конфига.
- Агенты отправляют heartbeats и check events на сервер через `/api/v1`.
- FastAPI server владеет inventory, текущим состоянием checks, incidents,
  retention и retry для notifier outbox.
- Next.js UI показывает agents, checks, incidents, events и delivery state
  уведомлений.
- Новый agent key должен пройти operator admission, прежде чем сможет влиять на
  monitoring state.
- Server и agents экспортируют Prometheus metrics для самого Monlet.

## Скриншоты

Agents и admission state:

![Страница агентов Monlet](docs/assets/readme/agents.png)

Текущие check states:

![Страница проверок Monlet](docs/assets/readme/checks.png)

Open и resolved incidents:

![Страница инцидентов Monlet](docs/assets/readme/incidents.png)

Состояние notifier outbox:

![Страница outbox Monlet](docs/assets/readme/outbox.png)

## Возможности в 0.1.0

- Локальные command checks со статусами `ok`, `warning`, `critical` и `unknown`.
- Timeout для каждой проверки и best-effort resource limits для scripts: CPU
  time, virtual memory и open files.
- Agent liveness по heartbeat: alive, stale и dead.
- Durable on-disk spool в агенте на случай outage сервера.
- Idempotent event ingestion и replay без дублей.
- Server-owned lifecycle для открытия и закрытия incidents.
- Notification outbox со статусами retry и failure.
- Debug, webhook, Telegram и Alertmanager notifier implementations.
- Agent admission и blacklist controls.
- Partitioned PostgreSQL event storage и bounded retention.
- Docker Compose local stack и showcase stand.
- Prometheus metrics для server и agent runtime behavior.

## Быстрый старт

Запустить локальный stack:

```sh
cd deploy
MONLET_AUTH_TOKEN=$(openssl rand -hex 16) docker compose up --build
```

Сервисы:

- 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>

Запустить полный demo stand:

```sh
SHOWCASE_KEEP=1 bash deploy/e2e-showcase.sh
```

Showcase поднимает PostgreSQL, server, web UI, mock webhook и несколько demo
agents. Он прогоняет mixed check states, liveness transitions, resolved
incidents, notifier retries/failures и spool replay.

## Архитектура

Monlet - monorepo с тремя независимыми приложениями:

- `agent/` - Go binary для monitored hosts.
- `server/` - Python/FastAPI backend с PostgreSQL storage.
- `web/` - Next.js operator dashboard.

Server владеет lifecycle инцидентов и уведомлений. Agent отправляет только
факты. Web UI read-only для monitoring state; agent admission и blacklist
controls - mutation surface для v1.

Публичный API contract лежит в `api/openapi.yaml`. Design и operations docs
начинаются с `docs/index.md`.

## Не цели

Monlet 0.1.0 намеренно не является:

- remote command runner;
- системой remote config push;
- заменой Grafana;
- полноценной incident-management платформой;
- multi-tenant RBAC продуктом;
- Kubernetes operator;
- distributed server cluster.

## Разработка

Начинать отсюда:

1. [deploy/README.md](deploy/README.md)
2. [agent/README.md](agent/README.md)
3. [server/README.md](server/README.md)
4. [web/README.md](web/README.md)
5. [api/README.md](api/README.md)
6. [docs/index.md](docs/index.md)

Dependency caches и virtual environments хранятся внутри репозитория. Актуальные
команды local development описаны в component README.

## Статус

Monlet - активный early-stage проект. Release 0.1.0 пригоден для local
development, demos и controlled internal deployments. Internal contracts ещё
могут меняться, при этом public API остаётся versioned under `/api/v1`.

`0.1.0` - версия product release. `/api/v1` - namespace API.

## Лицензия

MIT.