# Deployment Notes

These notes describe the intended production shape. Use
[`docs/ops/deployment-checklist.md`](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`](backup-restore.md) before first production
use. Agent spools are best-effort buffers and are not a substitute for database
backups.