Monitoring Kresus with Vigilmon

Kresus is the open-source personal finance manager that pulls your bank transactions, categorizes them automatically, and keeps everything private on your own server. It connects to banks via the Woob library, imports OFX/CSV files, and sends budget alerts — all without touching a third-party cloud. But when you run your own finance tool, you also own its uptime. A broken bank sync or a failed scheduled import means you're making financial decisions on stale data. Vigilmon gives you continuous monitoring across every Kresus service layer so failures are caught before they affect your financial visibility.

What You'll Set Up

• Kresus web server availability (port 9876)
• Bank account data sync service (Woob integration) health
• Transaction import pipeline monitoring
• Alert notification delivery monitoring
• Database connectivity (SQLite or PostgreSQL)
• CSV/OFX export service health
• Scheduled auto-sync job heartbeat

Prerequisites

• Kresus installed and running (self-hosted via Docker, Node.js, or YunoHost)
• A free Vigilmon account

Step 1: Monitor the Kresus Web Server

Kresus serves its web interface on port 9876 by default. This is your primary availability check.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your Kresus URL: http://your-server:9876 (or your proxied HTTPS URL if you've put nginx in front).
4. Set Check interval to 2 minutes.
5. Set Expected HTTP status to 200.
6. Click Save.

Kresus redirects unauthenticated requests to the login page. To get a meaningful health check, probe the API ping endpoint that Kresus exposes:

http://your-server:9876/api/ping

This endpoint returns {"pong":"pong"} with status 200 when the server is healthy, without requiring authentication. Set Expected HTTP status to 200 and add a keyword check for pong.

Step 2: Monitor Bank Account Sync (Woob Integration)

Kresus fetches bank transactions via Woob — a Python library that interfaces with hundreds of bank websites. Bank sync is the most fragile part of Kresus: bank websites change their HTML, banks add CAPTCHAs, or session tokens expire. When sync breaks, your transaction list goes stale silently.

Add a cron heartbeat to verify that syncs are completing successfully:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected interval to match your auto-sync schedule (e.g., 6 hours for twice-daily syncs).
3. Copy the heartbeat URL.
4. Create a script that queries the Kresus database for recent sync timestamps:

#!/bin/bash
KRESUS_DB="/path/to/kresus/data/db.sqlite"

# Check if any account was synced in the last 7 hours
LAST_SYNC=$(sqlite3 "$KRESUS_DB" \
  "SELECT COUNT(*) FROM accounts WHERE last_checked > datetime('now', '-7 hours')")

if [ "$LAST_SYNC" -gt "0" ]; then
  curl -s https://vigilmon.online/heartbeat/YOUR_SYNC_HEARTBEAT_ID
fi

For PostgreSQL-backed Kresus, adapt the connection string:

LAST_SYNC=$(psql "$DATABASE_URL" -t -c \
  "SELECT COUNT(*) FROM accounts WHERE last_checked > NOW() - INTERVAL '7 hours'")

Schedule this check to run every hour. If no account has been synced in 7 hours when a 6-hour sync schedule is configured, the heartbeat stops and Vigilmon alerts you.

Step 3: Monitor the Transaction Import Pipeline

Beyond automatic bank sync, Kresus processes manual OFX and CSV imports. The import pipeline parses files, deduplicates transactions, and applies categorization rules. A broken import pipeline means manually uploaded files silently fail.

Check the Kresus API for import job status:

#!/bin/bash
KRESUS_URL="http://your-server:9876"
KRESUS_LOGIN="your-login"
KRESUS_PASSWORD="your-password"

# Test that the API accepts import-related requests
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -u "$KRESUS_LOGIN:$KRESUS_PASSWORD" \
  "$KRESUS_URL/api/accesses")

if [ "$STATUS" = "200" ]; then
  curl -s https://vigilmon.online/heartbeat/YOUR_IMPORT_HEARTBEAT_ID
fi

Schedule this every 30 minutes. The /api/accesses endpoint exercises the authentication layer and the database — if it returns 200, the import pipeline's underlying infrastructure is healthy.

Step 4: Monitor Alert Notification Delivery

Kresus can send budget alerts and transaction notifications via email. If the SMTP configuration is broken, you won't receive alerts for spending limits or unusual transactions — defeating the purpose of the alerting feature.

Add a cron heartbeat that verifies SMTP connectivity:

#!/bin/bash
SMTP_HOST="your-smtp-host"
SMTP_PORT="587"

# Test SMTP connectivity with a TCP check
if nc -z -w5 "$SMTP_HOST" "$SMTP_PORT" 2>/dev/null; then
  curl -s https://vigilmon.online/heartbeat/YOUR_EMAIL_HEARTBEAT_ID
fi

Schedule every 15 minutes. Alternatively, add a Vigilmon TCP monitor directly:

1. Add a TCP monitor in Vigilmon.
2. Set Host to your SMTP server.
3. Set Port to 587 (or 465 for SMTPS, 25 for plain SMTP).
4. Set Check interval to 5 minutes.

Step 5: Monitor Database Connectivity

Kresus supports both SQLite (default) and PostgreSQL for storing transactions, categories, alerts, and sync history. A database failure stops all Kresus functionality.

For SQLite (the default), verify the database file is accessible and not corrupted:

#!/bin/bash
KRESUS_DB="/path/to/kresus/data/db.sqlite"

# Quick integrity check
INTEGRITY=$(sqlite3 "$KRESUS_DB" "PRAGMA quick_check;" 2>/dev/null)

if [ "$INTEGRITY" = "ok" ]; then
  curl -s https://vigilmon.online/heartbeat/YOUR_DB_HEARTBEAT_ID
fi

Schedule every 10 minutes.

For PostgreSQL, add a TCP monitor:

1. Add a TCP monitor in Vigilmon.
2. Set Host to your PostgreSQL server hostname.
3. Set Port to 5432.
4. Set Check interval to 1 minute.
5. Click Save.

Step 6: Monitor CSV/OFX Export Service

Kresus can export your transaction history as CSV or OFX files. While export failures are lower-priority than sync failures, a broken export means you can't feed data into tax software or spreadsheets at a critical time.

Probe the export API to verify it's responsive:

#!/bin/bash
KRESUS_URL="http://your-server:9876"
KRESUS_LOGIN="your-login"
KRESUS_PASSWORD="your-password"

# Test export endpoint availability (requires an account ID)
ACCOUNT_ID=$(curl -s -u "$KRESUS_LOGIN:$KRESUS_PASSWORD" \
  "$KRESUS_URL/api/accesses" | jq -r '.[0].id // empty')

if [ -n "$ACCOUNT_ID" ]; then
  curl -s https://vigilmon.online/heartbeat/YOUR_EXPORT_HEARTBEAT_ID
fi

Schedule daily — export failures are less urgent but worth knowing about before you actually need an export.

Step 7: Monitor the Scheduled Auto-Sync Job

Kresus's automatic sync scheduler runs as part of the Node.js process. If the scheduler crashes or the process memory becomes exhausted, sync stops running even though the web server appears healthy.

Add a cron heartbeat that verifies the scheduler is active by checking Kresus process health and confirming the sync scheduler loop is running:

#!/bin/bash
# Verify Kresus process is running and consuming reasonable memory
KRESUS_PID=$(pgrep -f "kresus" | head -1)

if [ -n "$KRESUS_PID" ]; then
  MEM_MB=$(ps -o rss= -p "$KRESUS_PID" | awk '{print int($1/1024)}')
  
  # Alert if process exists and memory is under 1GB (not OOM-thrashing)
  if [ "$MEM_MB" -lt "1024" ]; then
    curl -s https://vigilmon.online/heartbeat/YOUR_SCHEDULER_HEARTBEAT_ID
  fi
fi

Schedule every 30 minutes, matching roughly half your sync interval.

Step 8: Configure SSL Certificate Monitoring

If you've put Kresus behind nginx or a reverse proxy with HTTPS, the certificate is critical — especially if you access Kresus from mobile or outside your home network.

1. Open the HTTP monitor you created for your Kresus URL in Step 1.
2. Enable Monitor SSL certificate.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

Let's Encrypt certificates for Kresus are typically renewed by certbot or acme.sh running on the same host. A 21-day alert window gives you enough time to investigate renewal failures.

Step 9: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add email or a mobile push webhook.
2. For the bank sync heartbeat, set Consecutive failures before alert to 1 — a missed sync is always worth knowing about.
3. For the web server monitor, set to 2 — brief restarts during updates are normal.
4. Consider routing bank sync and database alerts to a higher-priority channel than the web server alert.

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP web server | /api/ping | Kresus server down | | Cron heartbeat | Bank sync timestamp check | Bank sync stalled or broken | | Cron heartbeat | API access check | Import pipeline broken | | TCP / Heartbeat | SMTP port | Alert emails not sending | | TCP / Heartbeat | Database check | SQLite corruption or PostgreSQL down | | Cron heartbeat | Export API check | CSV/OFX export broken | | Cron heartbeat | Process health check | Auto-sync scheduler not running | | SSL certificate | Kresus HTTPS domain | Certificate expiry |

Kresus gives you full ownership of your financial data — but that ownership includes keeping the sync pipeline healthy. With Vigilmon watching every layer from the web interface to the bank sync scheduler, you'll always know whether your financial data is fresh or stale.