Monitoring and health

Installation status

System → Installation status checks everything Vaultigen depends on and shows a green, amber or red state for each:

Check	Looks at
Database	Connection and engine
Sodium	The PHP extension for encryption
Installation identity	installation.json or its environment equivalents
Application key	APP_KEY
Independent security keys	KEK keyring and audit key
Storage headroom	Free space on the storage volume
Mail	Transport configured; you can send a test
Scheduler	Recent scheduler heartbeat
Queue	Recent worker heartbeat
Security notifications	Pending or failed deliveries
License	License state and seats in use

Heartbeats go stale after three minutes. Presence checks show only whether something exists, never a value, and do not prove that backups are restorable.

Background processes

Process	Responsible for
Queue worker (queue:work)	Backups, key rotation, imports, site icons, worker heartbeat
Scheduler (schedule:work or cron)	Security notifications, emergency-access expiry, trash purge, import cleanup, audit pruning, heartbeats

Both must run under a supervisor. Jobs are durable: if the worker was down, it picks them up after a restart. On Docker Compose, the worker and scheduler services are that supervisor: they restart automatically and report their heartbeats through container health checks.

Queue timeouts matter: the queue connection’s retry_after must be longer than the longest job (VAULTIGEN_BACKUP_JOB_TIMEOUT and VAULTIGEN_ROTATION_JOB_TIMEOUT, one hour by default). The shipped defaults satisfy this.

Disk headroom

Backups, attachments and import staging consume disk. Configure the volume and the warning threshold:

VAULTIGEN_STORAGE_PATH=/var/www/vaultigen/storage/app/private
VAULTIGEN_MIN_FREE_BYTES=268435456   # 256 MB, the default

The check warns; it does not take the application down. Also keep an eye on PHP’s temporary directory. On Docker Compose, the default already checks data/storage/; backup sets in backups/ usually share its file system.

Daily checks

• Installation status: all green, heartbeats recent.
• System → Operations: the last backup completed, nothing stuck in running.
• Activity: unexpected auth.* denials, emergency-access sessions or key rotations you did not start.

Docker Compose

docker compose ps                                     # every service running and healthy?
docker compose logs --tail=100 web worker scheduler   # recent output
docker compose logs --tail=100 migrate                # why the application did not start

• web is healthy when it answers locally; worker and scheduler when their heartbeats are recent (php artisan vaultigen:health worker|scheduler). An unhealthy service shows (unhealthy) in docker compose ps.
• migrate runs on every start and then exits. Exit code 0 is normal; anything else keeps the application stopped.
• Watch free space with df -h on the file system that holds ~/vaultigen: database, attachments and backup sets all live there.
• Containers that were running restart after a reboot. After host maintenance, check docker compose ps and Installation status.

Logs

On Docker Compose, application and web-server logs go to the container output (docker compose logs); there is no access log. Rotate Docker’s logs with its logging driver settings. On a manual installation, application logs are written to storage/logs. They never contain secret values, and nobody should ever paste a live secret into a ticket or log.

External monitoring

Recommended additions outside Vaultigen: an HTTPS uptime check, an alert when a backup fails or none succeeded in the last day (the Operations page warns after 48 hours), disk-space alerts on the host, and an alert on failed security notifications.