Monitoring & Logs

Health endpoint

GET /api/health

Returns a JSON status:

{
  "status": "ok",
  "database": "connected",
  "storage": "connected"
}

When database and object storage are reachable the endpoint responds with HTTP 200. If a component fails, status becomes degraded, the affected field names the cause (e.g. error: … or bucket_missing) and the endpoint responds with HTTP 503 — external monitors should therefore check the HTTP status.

Use this endpoint with external monitoring systems (e.g., Uptime Kuma).

Log streams

Clavis writes four log files:

Stream	Path	Content
audit.log	/logs/audit.log	Security-relevant events (HMAC chain)
app.log	/logs/app.log	Application logs
error.log	/logs/error.log	Errors and exceptions
access.log	/logs/access.log	HTTP requests

Logs are stored in the Docker volume clavis_logs and are rotated daily.

Retention periods

Stream	Retention
Audit logs	365 days
App logs	90 days
Error logs	90 days
Access logs	90 days

Log cleanup

The cleanup script removes logs past their retention period:

deployment/scripts/log-cleanup.sh

Recommended as a daily cron job:

# crontab -e
0 4 * * * /path/to/App/deployment/scripts/log-cleanup.sh

External monitoring

Recommendation: Uptime Kuma on a separate server, polling the health endpoint every 60 seconds and sending alert notifications (e.g., Telegram).