Monitoring Flatnotes with Vigilmon

Flatnotes is a refreshingly simple self-hosted note-taking app: no database, no cloud sync, just markdown files in a folder and a FastAPI web server in front of them. It runs on Python at port 8080 and stays out of your way. The simplicity is its strength — and also where its failure modes hide. A full disk, a file permission change, or a search index rebuild that locks up can take Flatnotes offline in ways that are completely invisible without external monitoring. Vigilmon watches the parts you can't see from inside the app.

What You'll Set Up

• HTTP uptime monitoring for the Flatnotes web server
• File system accessibility check
• Search index health probe
• Authentication endpoint monitoring
• Note sync response time tracking
• Instant alerts for any failure

Prerequisites

• Flatnotes running (default port 8080, via Docker or direct Python)
• A free Vigilmon account

Why Flatnotes Monitoring Matters

Flatnotes looks simple, but "no database" doesn't mean "nothing can go wrong":

• HTTP server down — if the FastAPI process crashes or Docker container exits, notes are completely inaccessible
• File system inaccessible — if the mounted volume unmounts, disk fills up, or permissions change, notes can't be read or written; the app may start but return errors on every note access
• Search index failure — Flatnotes builds and caches a search index; if it becomes stale or corrupted after an ungraceful shutdown, search stops working
• Authentication broken — if the auth endpoint is down or misconfigured, no one can log in; the app appears up but is completely unusable
• Slow response times — if the note folder grows large and indexing slows down on every request, performance degrades gradually until the app becomes unusable

None of these generate loud errors on their own. They require external probes to detect.

Step 1: Monitor the Flatnotes Web Server

Flatnotes serves its UI at port 8080. Add an HTTP uptime monitor:

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

If you're running Flatnotes behind a reverse proxy (nginx, Caddy, Traefik), add a second monitor for the public-facing URL. Proxy misconfigurations are a common failure point, and monitoring both the proxy and the app directly lets you distinguish "proxy is broken" from "app is broken."

To verify the server is running locally before setting up the monitor:

curl -I http://your-flatnotes-host:8080
# HTTP/1.1 200 OK

Step 2: Monitor the FastAPI Health Endpoint

FastAPI (the framework Flatnotes uses) exposes a standard /health endpoint. This is a fast, low-overhead probe that confirms the Python process is alive and the web framework is responding:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-flatnotes-host:8080/health
3. Expected status: 200
4. Check interval: 2 minutes
5. Save.

Verify it returns a valid response:

curl http://your-flatnotes-host:8080/health
# {"status":"ok"}

If Flatnotes doesn't expose a /health endpoint in your version, the root URL monitor from Step 1 is sufficient. You can check what API routes are available at:

curl http://your-flatnotes-host:8080/openapi.json | python3 -m json.tool | grep '"path"'

Step 3: Check File System Accessibility

Flatnotes reads and writes directly to a directory of markdown files. If that directory becomes unreadable (volume unmount, permission change, disk full), every note operation fails. The server stays "up" but returns errors on every request.

Add a cron heartbeat driven by a server-side script that verifies the notes directory is accessible:

#!/bin/bash
# /usr/local/bin/flatnotes-fs-check.sh
NOTES_DIR="/path/to/flatnotes/notes"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_HEARTBEAT_TOKEN"

# Check directory is readable
if [ -r "$NOTES_DIR" ] && [ -w "$NOTES_DIR" ]; then
    # Check disk usage is below 85%
    USAGE=$(df "$NOTES_DIR" | awk 'NR==2 {print $5}' | tr -d '%')
    if [ "$USAGE" -lt 85 ]; then
        curl -s "$HEARTBEAT_URL"
    fi
fi

Make it executable and schedule it:

chmod +x /usr/local/bin/flatnotes-fs-check.sh

Add to crontab:

*/5 * * * * /usr/local/bin/flatnotes-fs-check.sh

In Vigilmon:

1. Click Add Monitor → Cron Heartbeat.
2. Expected interval: 5 minutes.
3. Copy the heartbeat URL and set it in the script.
4. Save.

If the script doesn't ping (directory inaccessible, disk nearly full), you get alerted within 5 minutes.

Step 4: Monitor Search Index Health

Flatnotes uses whoosh (or a similar in-process search library) to maintain a search index over your markdown files. After an ungraceful shutdown or a large batch of file changes, the index can become stale or corrupted. Searches return no results or raise an error — with no visible indication to the user.

Add a search probe that actually performs a search and verifies a result comes back:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-flatnotes-host:8080/api/search?q=test (adjust to match Flatnotes' actual search API path).
3. Expected status: 200
4. Check interval: 5 minutes
5. Save.

To find the correct search endpoint:

curl "http://your-flatnotes-host:8080/api/search?q=a" -H "Authorization: Bearer YOUR_TOKEN"

If search is working, you'll get a JSON array (even if empty). A 500 or timeout indicates index failure.

For the monitor to be meaningful, include an Authorization header if Flatnotes requires authentication. Use Vigilmon's Custom Headers field:

• Header: Authorization
• Value: Bearer YOUR_TOKEN

Step 5: Monitor Authentication Endpoint Availability

Flatnotes supports username/password authentication. If the auth endpoint is broken, no user can log in — even if all the notes are intact. Monitor the authentication endpoint directly:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-flatnotes-host:8080/api/token (or wherever Flatnotes handles login).
3. Set Method to POST.
4. Expected status: 422 (FastAPI returns 422 Unprocessable Entity for a request with missing fields, which confirms the endpoint is reachable and responding — not 404 or 500).
5. Check interval: 5 minutes.
6. Save.

The 422 response is intentional here: you're not trying to log in (that would require real credentials), you're confirming the auth endpoint exists and is responding. A 404 means the route disappeared; a 500 means something is broken on the server side.

Step 6: Track Response Time Trends

One of Flatnotes' failure modes is gradual: as the notes directory grows, indexing and file scanning can slow down. Performance degrades over months until the app becomes sluggish. Vigilmon tracks response time on every check — use that data to catch slowdowns early.

In Vigilmon, on your main web server monitor:

1. Click on the monitor → Settings.
2. Enable Alert on slow response and set a threshold (e.g. alert if response time exceeds 3 seconds).
3. Save.

Check the response time chart periodically. A gradual upward slope over weeks is a signal that your notes directory may need indexing optimization or that the server needs more RAM.

Step 7: Configure Alert Channels

1. In Vigilmon, go to Alert Channels → Add Channel.
2. Add Slack or email.
3. Set Consecutive failures before alert to 2 on the web server monitor to avoid false alarms from brief Docker restarts.
4. Set to 1 for the filesystem heartbeat — a missed ping here is always significant.
5. Enable alerts on all monitors.

Alert example:

🔴 DOWN: flatnotes.yourdomain.com:8080
Status: Connection refused
Detected: 1 minute ago

Heartbeat missed alert:

🔴 MISSED: Flatnotes filesystem check
Expected every: 5 minutes
Last ping received: 12 minutes ago

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web server | :8080 | FastAPI crash, container exit | | Health endpoint | /health | Process up but unhealthy | | File system | Cron heartbeat | Volume unmount, disk full, permission error | | Search index | /api/search?q=test | Index corruption, search API failure | | Auth endpoint | /api/token (POST) | Login broken even when app appears up | | Response time | Web server latency | Gradual slowdown as notes directory grows |

Flatnotes earns its name — flat file, no database, minimal overhead. Vigilmon adds the one thing it doesn't have: visibility into the moments when that simplicity hits a limit.

Get started free at vigilmon.online.