monlet/docs/ops/deployment.md

Deployment Notes

These notes describe the intended production shape. Use docs/ops/deployment-checklist.md for the step-by-step first stand-up checklist.

Agent

The agent runs on monitored hosts as a systemd service.

Expected paths:

• binary: /usr/local/bin/monlet-agent
• config: /etc/monlet/agent.toml
• state: /var/lib/monlet-agent
• logs: journald

The agent reads only local config. It does not accept remote command execution or remote config push from the server. Per-check scheduling is local to the agent, and overlapping runs for the same check are skipped.

Server

The server runs as a containerized FastAPI application backed by PostgreSQL 16+. It owns inventory, current check state, incidents, notification outbox state, retention, and public /api/v1 contracts.

Required production boundaries:

• TLS and rate limiting at a reverse proxy
• PostgreSQL as canonical storage
• MONLET_AUTH_TOKEN stored in a secret manager
• request body limits enabled
• structured logs with auth material redacted
• /api/v1/health, /api/v1/ready, and /metrics exposed for operations

Docker images install dependencies inside the image. Do not mount host virtual environments into server containers.

Web

The web app is an operator dashboard. Monitoring pages are read-only; agent admission and blacklist controls are the explicit v1 write surface.

Protect the UI with either local web login or a trusted auth proxy. If local login is enabled, rate-limit /login at the reverse proxy. Monlet v1 does not provide full RBAC.

Observability

The local deploy stack includes optional Prometheus, Alertmanager, and Grafana examples under deploy/. Production deployments should at minimum scrape:

• Monlet server /metrics
• each agent /metrics
• reverse-proxy and PostgreSQL metrics from the surrounding environment

Metric labels must stay low-cardinality. Do not put timestamps, request IDs, or unbounded host-local values into check IDs or labels.

Backups

PostgreSQL is the canonical state. Follow docs/ops/backup-restore.md before first production use. Agent spools are best-effort buffers and are not a substitute for database backups.