tutorial

Monitoring Teedy with Vigilmon

Teedy is a self-hosted lightweight document management system running on Java and port 8080 — but a crashed Lucene index or failed thumbnail service kills search and previews silently. Here's how to monitor Teedy with Vigilmon.

Teedy (formerly Sismics Docs) is a lean, self-hosted document management system built in Java. It handles file uploads, full-text indexing via Lucene, thumbnail generation, and user authentication — all in a single JVM process. That simplicity is a strength, but it also means a single stuck thread can silently degrade multiple features at once. Vigilmon watches Teedy's REST API endpoints, database connectivity, and background services so you catch failures before your users notice.

What You'll Set Up

  • Web application availability on port 8080
  • REST API health check
  • Full-text search endpoint monitoring
  • Document indexing service health
  • Database connectivity check
  • Thumbnail generation service monitoring
  • User authentication endpoint verification

Prerequisites

  • Teedy 1.10+ running on port 8080
  • Admin credentials for the Teedy web UI
  • A free Vigilmon account

Step 1: Monitor Web Application Availability

Teedy serves its web interface from the embedded Jetty server on port 8080. The root path returns a 302 redirect to the login page.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter: http://your-teedy-host:8080/
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 302 (the root redirects to /src/index.html).
  6. Alternatively, set the URL to http://your-teedy-host:8080/src/index.html with expected status 200.
  7. Click Save.

This confirms Jetty is up and the static resources are being served.

Step 2: Monitor the REST API

Teedy exposes a REST API at /api/. The /api/app endpoint returns application version and status information — a lightweight probe that exercises the full API stack:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-teedy-host:8080/api/app
  3. Expected HTTP status: 200
  4. Expected body contains: "current_version"
  5. Check interval: 1 minute
  6. Click Save.

A 500 from this endpoint typically means an uncaught exception in the application layer, often related to a failed database connection or Lucene index corruption.

Step 3: Monitor User Authentication

The login API endpoint exercises authentication, database reads, and session management in a single call:

  1. Add an HTTP / HTTPS monitor.
  2. URL: http://your-teedy-host:8080/api/user/login
  3. Method: POST
  4. Request body: username=admin&password=YOUR_ADMIN_PASSWORD
  5. Content-Type header: application/x-www-form-urlencoded
  6. Expected HTTP status: 200
  7. Check interval: 2 minutes
  8. Click Save.

A 403 means invalid credentials (check your monitor config); a 500 means the authentication service or database is failing.

Security note: Use a dedicated read-only monitoring user in Teedy for this probe rather than your main admin credentials.

Step 4: Monitor Full-Text Search

Teedy uses Lucene for full-text search across document content. A corrupt or locked Lucene index causes search to return empty results with no visible error in the UI.

  1. Add an HTTP / HTTPS monitor.
  2. URL: http://your-teedy-host:8080/api/document/list?limit=1
  3. Add header Cookie: auth_token=YOUR_AUTH_TOKEN (obtain this from a browser session or the login API response).
  4. Expected HTTP status: 200
  5. Expected body contains: "total"
  6. Check interval: 5 minutes
  7. Click Save.

This exercises the Lucene query path. A 500 response means Lucene failed to execute the query, indicating index corruption or a thread pool exhaustion.

Step 5: Monitor Document Indexing Health

New documents need to be OCR'd and indexed by Lucene before they appear in search results. Teedy runs indexing asynchronously in background threads. Monitor the indexing queue via the admin API:

  1. Add an HTTP / HTTPS monitor.
  2. URL: http://your-teedy-host:8080/api/app/log
  3. Header: Cookie: auth_token=YOUR_AUTH_TOKEN
  4. Expected HTTP status: 200
  5. Check interval: 5 minutes
  6. Click Save.

The log API confirms the application's background thread pool is alive. For deep indexing queue monitoring, tail the Teedy log file for ERROR entries related to Lucene and alert via a log monitoring tool alongside Vigilmon's endpoint checks.

Step 6: Monitor Database Connectivity

Teedy uses H2 (embedded, default) or a JDBC-compatible database. For production deployments using PostgreSQL or MySQL, add a TCP monitor:

  1. Click Add Monitor → TCP Port.
  2. Host: your database host.
  3. Port: 5432 (PostgreSQL) or 3306 (MySQL/MariaDB).
  4. Check interval: 1 minute.
  5. Click Save.

If you use the embedded H2 database, database failures manifest as 500 errors on the REST API endpoints rather than TCP failures. The API health check from Step 2 covers this case.

Step 7: Monitor Thumbnail Generation

Teedy generates document thumbnails using ImageMagick or a built-in renderer. Failed thumbnails appear as broken image icons in the document list — a subtle UX failure that's easy to miss.

  1. Add an HTTP / HTTPS monitor.
  2. URL: http://your-teedy-host:8080/api/document/list?limit=1
  3. Header: Cookie: auth_token=YOUR_AUTH_TOKEN
  4. Expected HTTP status: 200
  5. Check interval: 5 minutes

After verifying the list endpoint works, monitor a specific document thumbnail:

  1. Upload a test document via the Teedy web UI.
  2. Note its document ID from the URL.
  3. Add a monitor for: http://your-teedy-host:8080/api/file/DOCUMENT_ID/thumbnail
  4. Expected HTTP status: 200
  5. Check interval: 10 minutes

A 500 on the thumbnail endpoint means ImageMagick or the file storage backend failed.

Step 8: Monitor File Storage Backend

Teedy stores uploaded files on disk. If the storage path fills up or the mount point is lost, uploads fail silently.

Add a cron heartbeat driven by a storage check script:

  1. In Vigilmon, click Add Monitor → Cron Heartbeat.
  2. Expected interval: 10 minutes.
  3. Copy the heartbeat URL.
  4. Create a script on the Teedy host:
#!/bin/bash
# Checks disk space on Teedy storage mount
STORAGE_PATH="/opt/teedy/data"
USAGE=$(df "$STORAGE_PATH" | awk 'NR==2 {print $5}' | tr -d '%')

if [ "$USAGE" -lt 90 ]; then
  curl -s https://vigilmon.online/heartbeat/abc123
fi
  1. Add to cron: */10 * * * * /opt/scripts/teedy_storage_check.sh

If disk usage exceeds 90% or the storage mount is lost, the heartbeat stops and Vigilmon alerts.

Step 9: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and add Slack, email, or PagerDuty.
  2. For the web application monitor, set Consecutive failures before alert to 2 — Teedy's JVM takes 20–30 seconds to restart.
  3. For the authentication monitor, set Consecutive failures before alert to 2 — network latency can occasionally cause a timeout.
  4. For the storage heartbeat, set Consecutive failures before alert to 1 — a missed heartbeat means storage is either full or unreachable.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web application | :8080/src/index.html | Jetty crash, static asset failure | | REST API | :8080/api/app | Application layer failure | | Authentication | :8080/api/user/login | Auth service, session DB failure | | Full-text search | :8080/api/document/list | Lucene index corruption | | Thumbnail generation | :8080/api/file/ID/thumbnail | ImageMagick failure | | Database | :5432 / :3306 TCP | External DB connectivity loss | | Storage heartbeat | Heartbeat URL | Disk full, mount lost |

Teedy's simplicity — a single Java process managing documents, search, and thumbnails — makes it fast to deploy but means a single failure can impact multiple features at once. With Vigilmon covering each REST API endpoint, database connectivity, and storage health, you get immediate visibility into every failure mode before your users open a support ticket.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles