Paperless-ngx is a self-hosted document management system that scans, OCRs, and indexes your physical and digital documents — replacing filing cabinets and scattered PDF folders with a searchable, tagged archive. When the Paperless-ngx API goes down, document ingestion stops, scheduled OCR jobs queue silently, and users can't retrieve their documents. The Celery worker processes OCR and file ingestion tasks asynchronously via Redis — if it crashes, new documents pile up in the inbox unprocessed without any visible error in the web UI. Vigilmon gives you external visibility into Paperless-ngx's API, web interface, worker heartbeat, and SSL certificate so failures surface within 60 seconds.
What You'll Build
- An HTTP alive check on Paperless-ngx's
/api/endpoint - An HTTP monitor for the Paperless-ngx web UI
- A cron job monitor for the Celery worker heartbeat
- SSL certificate monitoring for your Paperless-ngx domain
- An alerting setup that separates API failures from background worker failures
Prerequisites
- A running Paperless-ngx instance with a public or network-reachable domain
- HTTPS configured (e.g.,
https://paperless.example.com) - Shell access to your Paperless-ngx server (for the worker heartbeat cron job)
- A free account at vigilmon.online
Step 1: Verify Paperless-ngx's API Alive Check
Paperless-ngx exposes its REST API root at /api/. This endpoint requires authentication for full use, but it returns HTTP 401 Unauthorized when the server is alive and the authentication layer is functioning — a 401 response means Paperless-ngx is running and serving requests correctly:
curl -o /dev/null -s -w "%{http_code}" https://paperless.example.com/api/
A healthy Paperless-ngx instance returns HTTP 401 with a JSON body:
{
"detail": "Authentication credentials were not provided."
}
A 401 response confirms the Django application server is running, the database connection is healthy, and the REST framework is properly configured. A 502 or 503 indicates a reverse proxy failure or a crashed application server.
Step 2: Create a Vigilmon HTTP Monitor for the API Endpoint
Vigilmon supports monitoring endpoints that return non-200 status codes as expected alive signals:
- Log in to Vigilmon → Add Monitor → HTTP.
- URL:
https://paperless.example.com/api/. - Check interval: 60 seconds.
- Response timeout: 10 seconds.
- Expected status:
401. - Keyword:
Authentication credentials. - Label:
Paperless-ngx API. - Click Save.
This monitor catches:
- Paperless-ngx Django application server crashes (gunicorn process down)
- Database connectivity failures (PostgreSQL or SQLite)
- Application configuration errors after upgrades
- Container crashes due to resource exhaustion
The Authentication credentials keyword check verifies that the response is a genuine Paperless-ngx Django REST Framework response and not a reverse proxy error page returning 401.
Why 401 instead of 200? The Paperless-ngx API root requires authentication. Rather than managing API tokens in the monitoring setup, checking for a 401 response is the standard alive-check pattern for authenticated APIs — the server is provably alive and functional when it properly rejects unauthenticated requests.
Step 3: Monitor the Paperless-ngx Web UI
The Paperless-ngx web UI is a Vue.js single-page application served by the same Django/gunicorn stack or a separate nginx container depending on your deployment. Monitor it independently:
- Add Monitor → HTTP.
- URL:
https://paperless.example.com. - Check interval: 60 seconds.
- Expected status:
200. - Keyword:
Paperless. - Label:
Paperless-ngx Web UI. - Click Save.
This monitor catches reverse proxy failures, static file serving issues, and frontend container crashes that would prevent users from accessing their document archive in a browser, even if the API backend is still running.
Step 4: Set Up a Cron Job Monitor for the Celery Worker
Paperless-ngx's Celery worker processes all background tasks: OCR, document ingestion from the inbox folder, automatic tagging, file consumption, and scheduled tasks. If the worker crashes, documents pile up in the consumption directory unprocessed — with no visible error in the web UI.
Create the Vigilmon Cron Monitor
- Add Monitor → Cron Job / Heartbeat.
- Name:
Paperless-ngx Celery Worker. - Expected interval: Every 5 minutes.
- Grace period: 2 minutes.
- Label:
Paperless-ngx Worker Heartbeat. - Copy the unique Heartbeat URL that Vigilmon provides (e.g.,
https://vigilmon.online/ping/xxxxxxxx). - Click Save.
Configure the Heartbeat Cron Job
On your Paperless-ngx server, add a cron job that sends a heartbeat only when the Celery worker is alive. Create or edit /etc/cron.d/paperless-worker-heartbeat:
*/5 * * * * paperless cd /opt/paperless && docker compose exec -T webserver python manage.py shell -c "from paperless.celery import app; app.control.inspect().active()" && curl -fsS --retry 3 https://vigilmon.online/ping/xxxxxxxx > /dev/null 2>&1
Or for a bare-metal/venv deployment:
*/5 * * * * paperless /opt/paperless/venv/bin/celery -A paperless inspect active --timeout=5 > /dev/null 2>&1 && curl -fsS --retry 3 https://vigilmon.online/ping/xxxxxxxx > /dev/null 2>&1
Replace xxxxxxxx with your actual Vigilmon heartbeat URL. The && operator ensures the heartbeat ping is only sent when the Celery inspect command succeeds — a failed or unreachable worker suppresses the ping, triggering a Vigilmon alert after the grace period.
Alternative: If you prefer a simpler check, you can ping the heartbeat URL from within the worker itself using Celery's beat scheduler, sending a ping task every 5 minutes. This is more accurate because the ping comes from inside the worker process, not from an external probe.
Step 5: Monitor SSL Certificates
Paperless-ngx stores sensitive documents — tax records, contracts, medical documents, identity documents. An expired SSL certificate:
- Blocks browser access to your document archive
- Prevents mobile access via the Paperless-ngx Android or iOS app
- May prevent external document submission workflows from functioning
- Add Monitor → SSL Certificate.
- Domain:
paperless.example.com. - Alert when expiry is within: 30 days.
- Alert again: 14 days, 7 days, 3 days, 1 day.
- Click Save.
Step 6: Configure Alerting
In Vigilmon under Settings → Notifications, configure your alert channels:
| Monitor | Trigger | Action |
|---|---|---|
| /api/ | Non-401 or keyword missing | Check gunicorn/Django process; inspect database connection; review application logs |
| Web UI | Non-200 or keyword missing | Check reverse proxy; verify static files and frontend container |
| Celery Worker Heartbeat | No ping for > 7 minutes | Restart Celery worker container; check Redis connectivity; inspect worker logs |
| SSL certificate | < 30 days to expiry | Renew certificate; verify ACME/Let's Encrypt auto-renewal is running |
Alert after: 2 consecutive failures for HTTP monitors. 1 missed heartbeat for the worker monitor — a crashed Celery worker won't restart on its own.
Common Paperless-ngx Failure Modes and What Vigilmon Catches
| Scenario | Vigilmon monitor | |---|---| | Gunicorn process crash | API returns 502/503; alert within 60 s | | PostgreSQL database down | API returns 500; no document reads or writes | | Redis failure | Celery worker loses task queue; heartbeat stops; worker monitor fires | | Celery worker OOM-killed | Heartbeat stops; new documents queue unprocessed; worker monitor fires | | Consumption folder permissions issue | Worker alive but document ingestion silently fails | | Reverse proxy misconfiguration | Web UI monitor fires; API may still be reachable | | Disk full (document storage) | Worker fails on ingest; new files rejected | | SSL certificate expires | SSL monitor alerts at 30 days; all browser access blocked | | Migration failure after upgrade | API returns 500; database schema mismatch | | DNS misconfiguration | All monitors fire simultaneously |
Your document archive is the kind of data you only notice when it's missing — tax records, contracts, and identification documents that you need exactly when they're unavailable. Vigilmon watches Paperless-ngx's API, web interface, Celery worker, and SSL certificate so you're alerted within 60 seconds of any failure, long before a missing document causes a real problem.
Start monitoring Paperless-ngx in under 5 minutes — register free at vigilmon.online.