Monitoring Papermerge DMS with Vigilmon

Papermerge is a self-hosted document management system designed around scanning workflows and OCR-based full-text search. It digitises paper documents, invoices, contracts, and archival materials through Tesseract OCR running in Celery background workers — with Redis as the task broker and PostgreSQL storing all metadata. When the OCR pipeline stalls, file storage goes offline, or Redis drops, documents queue silently with no indication anything is wrong. Vigilmon gives you continuous visibility across the Django app server, PostgreSQL, Redis, Celery workers, file storage, the upload endpoint, and TLS certificate expiry — so a stalled scanning workflow pages you immediately.

What You'll Set Up

• HTTP uptime monitor for the Papermerge web UI (port 12000)
• PostgreSQL database connectivity heartbeat
• Redis connectivity monitor (Celery broker and cache)
• Celery OCR worker availability heartbeat
• File storage health check
• File upload endpoint monitor (scanning workflow integration)
• Full-text search health check
• Thumbnail generation service heartbeat
• TLS certificate expiry alert

Prerequisites

• Papermerge 2.x or 3.x running on your server (Docker Compose or native), accessible on port 12000
• Redis running and accessible from the server
• PostgreSQL running as the Papermerge database
• A free Vigilmon account

Step 1: Monitor the Papermerge Web UI

Papermerge's Django application serves the document management interface on port 12000. A crash here takes down browse, search, upload, and every user-facing operation.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your Papermerge URL: http://your-server-ip:12000.
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

If Papermerge is behind a reverse proxy (nginx or Caddy):

https://papermerge.yourdomain.com

To get a richer health signal than the root redirect, monitor the login page directly:

http://your-server-ip:12000/accounts/login/

Set Response body must contain to Login — this confirms the Django template engine is rendering correctly, not just that the port is open.

Step 2: Monitor PostgreSQL Database Connectivity

Papermerge stores all document metadata, folder hierarchies, user accounts, tags, and workflow states in PostgreSQL. A database connection failure prevents login, browsing, and all document operations.

Create a heartbeat script that verifies connectivity and run it on a cron schedule:

#!/bin/bash
# /usr/local/bin/papermerge-db-check.sh

HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_DB_HEARTBEAT_ID"
DB_HOST="${PAPERMERGE_DB_HOST:-localhost}"
DB_PORT="${PAPERMERGE_DB_PORT:-5432}"
DB_NAME="${PAPERMERGE_DB_NAME:-papermerge}"
DB_USER="${PAPERMERGE_DB_USER:-papermerge}"

# Check PostgreSQL connectivity
if pg_isready -h "$DB_HOST" -p "$DB_PORT" -d "$DB_NAME" -U "$DB_USER" -q; then
    curl -s "$HEARTBEAT_URL"
else
    echo "PostgreSQL not ready"
fi

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set expected interval to 2 minutes.
3. Copy the heartbeat URL into the script above.

Schedule the check:

crontab -e
# Add:
*/2 * * * * /usr/local/bin/papermerge-db-check.sh

Step 3: Monitor Redis Connectivity

Redis is Papermerge's Celery broker and cache backend. If Redis goes offline, OCR tasks stop being queued, background jobs stall, and newly uploaded documents never get processed — the UI appears healthy while the pipeline is dead.

Add a direct TCP port monitor for Redis:

1. In Vigilmon, click Add Monitor → TCP Port.
2. Enter your server hostname and port 6379.
3. Set Check interval to 1 minute.
4. Click Save.

For a deeper check that verifies Redis is accepting commands (not just that the port is open), add a heartbeat script:

#!/bin/bash
# /usr/local/bin/papermerge-redis-check.sh

HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_REDIS_HEARTBEAT_ID"
REDIS_HOST="${REDIS_HOST:-localhost}"
REDIS_PORT="${REDIS_PORT:-6379}"

# Send PING and verify PONG response
RESPONSE=$(redis-cli -h "$REDIS_HOST" -p "$REDIS_PORT" PING 2>/dev/null)

if [ "$RESPONSE" = "PONG" ]; then
    curl -s "$HEARTBEAT_URL"
else
    echo "Redis PING failed: $RESPONSE"
fi

Schedule every 2 minutes:

*/2 * * * * /usr/local/bin/papermerge-redis-check.sh

Step 4: Monitor Celery OCR Workers

Papermerge uses Celery workers to run Tesseract OCR on uploaded documents, generate thumbnails, and send email notifications. If workers go offline, uploaded documents queue indefinitely without being OCR-processed — users see documents with no searchable text and no thumbnails.

Create a heartbeat that verifies Celery workers are alive and processing:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set expected interval to 5 minutes.
3. Copy the heartbeat URL.

#!/bin/bash
# /usr/local/bin/papermerge-worker-check.sh

HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_WORKER_HEARTBEAT_ID"

# Check if Celery workers are running and responding to ping
WORKER_STATUS=$(celery -A papermerge.core inspect ping --timeout 10 2>/dev/null)

if echo "$WORKER_STATUS" | grep -q "pong"; then
    curl -s "$HEARTBEAT_URL"
else
    echo "No Celery workers responding"
fi

If running with Docker Compose, use the container name:

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_WORKER_HEARTBEAT_ID"

# Check Celery worker container is running and healthy
if docker exec papermerge-worker celery -A papermerge.core inspect ping --timeout 10 2>/dev/null | grep -q "pong"; then
    curl -s "$HEARTBEAT_URL"
fi

Schedule every 5 minutes:

*/5 * * * * /usr/local/bin/papermerge-worker-check.sh

Step 5: Monitor File Storage Health

Papermerge stores uploaded documents and their OCR results on disk (or in object storage). If the storage volume fills up, becomes read-only, or loses mount permissions, document uploads fail and OCR results cannot be saved — documents are lost silently.

#!/bin/bash
# /usr/local/bin/papermerge-storage-check.sh

HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_STORAGE_HEARTBEAT_ID"
STORAGE_DIR="${PAPERMERGE_MEDIA_ROOT:-/opt/papermerge/media}"
THRESHOLD_PCT=90

# Check directory is accessible and writable
if [ ! -d "$STORAGE_DIR" ]; then
    echo "Storage directory missing: $STORAGE_DIR"
    exit 1
fi

if [ ! -w "$STORAGE_DIR" ]; then
    echo "Storage directory not writable: $STORAGE_DIR"
    exit 1
fi

# Check disk usage
USAGE=$(df "$STORAGE_DIR" | awk 'NR==2 {gsub("%",""); print $5}')
if [ "$USAGE" -ge "$THRESHOLD_PCT" ]; then
    echo "Disk usage at ${USAGE}% — above ${THRESHOLD_PCT}% threshold"
    exit 1
fi

# Write and remove a test file
TEST_FILE="$STORAGE_DIR/.vigilmon_health_check"
if touch "$TEST_FILE" 2>/dev/null && rm "$TEST_FILE" 2>/dev/null; then
    curl -s "$HEARTBEAT_URL"
else
    echo "Cannot write to storage directory"
fi

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set expected interval to 5 minutes.

Schedule:

*/5 * * * * /usr/local/bin/papermerge-storage-check.sh

Step 6: Monitor the File Upload Endpoint

The document upload endpoint is the entry point for scanning workflow integrations — scanners, MFPs, and automation scripts POST documents to Papermerge via its REST API. If the upload endpoint fails, the entire scanning pipeline breaks at the source.

Papermerge's REST API requires authentication. Create a dedicated API health check using a token:

#!/bin/bash
# /usr/local/bin/papermerge-upload-check.sh

HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_UPLOAD_HEARTBEAT_ID"
PAPERMERGE_URL="http://localhost:12000"
API_TOKEN="YOUR_PAPERMERGE_API_TOKEN"

# Check API responsiveness — list documents endpoint
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" -m 10 \
  -H "Authorization: Token $API_TOKEN" \
  "$PAPERMERGE_URL/api/documents/")

if [ "$HTTP_CODE" = "200" ]; then
    curl -s "$HEARTBEAT_URL"
else
    echo "Upload API returned HTTP $HTTP_CODE"
fi

Get your API token from the Papermerge admin panel under User Profile → API Token.

Schedule every 5 minutes:

*/5 * * * * /usr/local/bin/papermerge-upload-check.sh

For direct HTTP monitoring (if your Papermerge instance uses token auth on a health endpoint):

1. In Vigilmon, click Add Monitor → HTTP / HTTPS.
2. Enter: http://your-server-ip:12000/api/documents/.
3. Add header: Authorization: Token YOUR_TOKEN.
4. Set Expected HTTP status to 200.
5. Set Check interval to 5 minutes.
6. Click Save.

Step 7: Monitor Full-Text Search Health

Papermerge indexes OCR-extracted text for full-text search — either through PostgreSQL's built-in FTS or Elasticsearch. A broken search index means documents are present but unsearchable, defeating the core purpose of an OCR-based DMS.

PostgreSQL Full-Text Search (default)

The PostgreSQL FTS index lives in the same database as document metadata. Verify your PostgreSQL heartbeat from Step 2 is active — a healthy database means FTS is available.

For an additional check, verify the search API endpoint responds:

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_SEARCH_HEARTBEAT_ID"
API_TOKEN="YOUR_PAPERMERGE_API_TOKEN"

HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" -m 15 \
  -H "Authorization: Token $API_TOKEN" \
  "http://localhost:12000/api/documents/?q=test")

if [ "$HTTP_CODE" = "200" ]; then
    curl -s "$HEARTBEAT_URL"
fi

Elasticsearch (if configured)

If Papermerge is configured to use Elasticsearch:

1. In Vigilmon, click Add Monitor → HTTP / HTTPS.
2. Enter: http://your-server-ip:9200/_cluster/health.
3. Set Expected HTTP status to 200.
4. Enable Response body must contain and enter green or yellow.
5. Set Check interval to 2 minutes.
6. Click Save.

Step 8: Monitor Thumbnail Generation

Papermerge generates page thumbnails for document preview in the UI. Thumbnails are generated by Celery workers alongside OCR. A stalled thumbnail pipeline means document previews show placeholder icons — users can't visually identify documents without opening them.

The thumbnail worker shares the same Celery pool as OCR workers. Your worker heartbeat from Step 4 covers both. Add an additional check targeting the thumbnail output directory:

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_THUMBNAIL_HEARTBEAT_ID"
THUMBNAIL_DIR="${PAPERMERGE_MEDIA_ROOT:-/opt/papermerge/media}/thumbnails"

# Verify thumbnails directory exists and has been written to recently
if [ -d "$THUMBNAIL_DIR" ] && [ -w "$THUMBNAIL_DIR" ]; then
    # Check for any file written in last 24 hours (normal active system)
    RECENT=$(find "$THUMBNAIL_DIR" -newer /tmp/.papermerge_thumb_ref -name "*.jpg" -o -name "*.png" 2>/dev/null | head -1)
    touch /tmp/.papermerge_thumb_ref
    curl -s "$HEARTBEAT_URL"
fi

Schedule every hour:

0 * * * * /usr/local/bin/papermerge-thumbnail-check.sh

Step 9: Monitor TLS Certificate Expiry

If Papermerge is exposed over HTTPS (via nginx or Caddy reverse proxy), an expired TLS certificate locks out all users and breaks scanner integrations that verify certificate validity.

1. In Vigilmon, open your web UI monitor from Step 1.
2. Enable Monitor SSL certificate.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

For a dedicated TLS monitor:

1. In Vigilmon, click Add Monitor → HTTP / HTTPS.
2. Enter: https://papermerge.yourdomain.com.
3. Enable Monitor SSL certificate and set alert to 21 days.
4. Set Check interval to 1 hour.
5. Click Save.

Step 10: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
2. Set Consecutive failures before alert to 2 on the web UI monitor — Django restarts can take a few seconds.
3. Set Consecutive failures before alert to 1 on the Redis and Celery monitors — a broken broker means no documents are processed from the moment it fails.

Route monitor failures by urgency:

• Redis down, Celery workers silent → Slack #papermerge-critical (immediate — OCR pipeline is dead)
• Web UI down, database unreachable → Slack #papermerge-alerts (urgent)
• Storage full, TLS expiry warning → email (investigate within 24 hours)

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI | http://server:12000 | Django process crash | | PostgreSQL | pg_isready heartbeat | Database connection failure | | Redis TCP | Port 6379 | Broker offline — no OCR tasks queued | | Celery workers | celery inspect ping | OCR pipeline dead | | File storage | Disk write heartbeat | Storage full or read-only | | Upload API | GET /api/documents/ | REST endpoint failure | | Full-text search | PostgreSQL or ES health | Search index unavailable | | Thumbnail dir | Directory write heartbeat | Preview generation stalled | | TLS certificate | HTTPS endpoint | Certificate expiry |

Papermerge's value is its OCR-powered search — but that search depends on a pipeline of Django, PostgreSQL, Redis, and Celery all running together. With Vigilmon watching each component, a stalled OCR worker or full disk pages you immediately instead of quietly accumulating unprocessed documents.