Monitoring OpenKM Enterprise DMS with Vigilmon

OpenKM is one of the longest-established open source enterprise document management systems, offering workflow automation, version control, metadata management, WebDAV file access, REST/SOAP APIs, and digital signatures — all running on a Java/Tomcat stack backed by PostgreSQL or MySQL and the Apache Jackrabbit Java Content Repository. When Tomcat runs out of threads, the JVM heap fills, or Jackrabbit's repository service stalls, document access fails across every interface: web UI, WebDAV mounts, and REST API integrations. Vigilmon gives you continuous health checks across the Tomcat server, OpenKM web UI, database, Jackrabbit JCR, Lucene search index, WebDAV endpoint, REST API, thread pool saturation, and JVM heap usage — so a Java OOM condition pages you before it takes down the DMS.

What You'll Set Up

• HTTP uptime monitor for the OpenKM web UI (port 8080)
• Tomcat application server availability check
• PostgreSQL or MySQL database connectivity heartbeat
• Jackrabbit JCR repository health check
• Lucene full-text search index monitor
• WebDAV endpoint availability check
• REST API health check
• Tomcat thread pool saturation monitor
• JVM heap usage monitor
• TLS certificate expiry alert

Prerequisites

• OpenKM running on Tomcat, accessible on port 8080 (or via reverse proxy)
• PostgreSQL or MySQL configured as the OpenKM database
• SSH access to the OpenKM host for scripted health checks
• A free Vigilmon account

Step 1: Monitor the OpenKM Web UI

OpenKM's login page at /OpenKM/ is the primary signal that the Tomcat container and Java application are serving requests. A failure here means the entire DMS is inaccessible.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter: http://your-server-ip:8080/OpenKM/.
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Enable Response body must contain and enter OpenKM.
7. Click Save.

The body check confirms OpenKM's JSP templates are rendering correctly — not just that Tomcat is listening.

If OpenKM is behind an nginx or Apache reverse proxy:

https://openkm.yourdomain.com/OpenKM/

Step 2: Monitor the Tomcat Application Server

Tomcat's manager application (if enabled) exposes a status endpoint. This lets you verify the servlet container itself is running, not just that the OpenKM application initialized correctly:

1. In Vigilmon, click Add Monitor → HTTP / HTTPS.
2. Enter: http://your-server-ip:8080/OpenKM/services/rest/auth/login.
3. Set Expected HTTP status to anything other than 5xx (401 or 200 depending on credentials).
4. Set Check interval to 1 minute.
5. Click Save.

Alternatively, monitor Tomcat's TCP port directly for a pure process availability check:

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

Step 3: Monitor Database Connectivity

OpenKM stores all document metadata, user permissions, workflow states, folder hierarchies, and document indexes in PostgreSQL or MySQL. A database outage freezes all DMS operations.

PostgreSQL

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

HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_DB_HEARTBEAT_ID"
DB_HOST="${OPENKM_DB_HOST:-localhost}"
DB_PORT="${OPENKM_DB_PORT:-5432}"
DB_NAME="${OPENKM_DB_NAME:-openkm}"
DB_USER="${OPENKM_DB_USER:-openkm}"

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 for OpenKM"
fi

MySQL / MariaDB

#!/bin/bash
# /usr/local/bin/openkm-mysql-check.sh

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

if mysqladmin ping -h "${MYSQL_HOST:-localhost}" -u "${MYSQL_USER:-openkm}" \
   -p"${MYSQL_PASSWORD}" --silent 2>/dev/null; then
    curl -s "$HEARTBEAT_URL"
else
    echo "MySQL not responding for OpenKM"
fi

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

Schedule:

*/2 * * * * /usr/local/bin/openkm-db-check.sh

Step 4: Monitor Jackrabbit JCR Repository Health

OpenKM uses Apache Jackrabbit as its Java Content Repository for document storage and versioning. Jackrabbit is an embedded service within the Tomcat JVM — it does not expose its own TCP port. Health is assessed via the OpenKM REST API, which depends on JCR being operational.

#!/bin/bash
# /usr/local/bin/openkm-jcr-check.sh

HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_JCR_HEARTBEAT_ID"
OPENKM_URL="http://localhost:8080/OpenKM"
OPENKM_USER="${OPENKM_ADMIN_USER:-okmAdmin}"
OPENKM_PASS="${OPENKM_ADMIN_PASS:-admin}"

# Authenticate and retrieve root folder — requires JCR to be operational
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" -m 15 \
  -u "$OPENKM_USER:$OPENKM_PASS" \
  "$OPENKM_URL/services/rest/folder/getChildren?fldId=%2Fokm%3Aroot")

if [ "$HTTP_CODE" = "200" ]; then
    curl -s "$HEARTBEAT_URL"
else
    echo "JCR repository check failed: HTTP $HTTP_CODE"
fi

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

Schedule:

*/3 * * * * /usr/local/bin/openkm-jcr-check.sh

Step 5: Monitor Lucene Full-Text Search

OpenKM uses Apache Lucene for full-text search across document content and metadata. If the Lucene index becomes corrupted or out of sync, search returns empty results while documents remain accessible through folder browsing — a silent failure that frustrates users.

Verify search is returning results via the REST API:

#!/bin/bash
# /usr/local/bin/openkm-search-check.sh

HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_SEARCH_HEARTBEAT_ID"
OPENKM_URL="http://localhost:8080/OpenKM"
OPENKM_USER="${OPENKM_ADMIN_USER:-okmAdmin}"
OPENKM_PASS="${OPENKM_ADMIN_PASS:-admin}"

# Execute a search — any response (even empty results) confirms Lucene is operational
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" -m 20 \
  -u "$OPENKM_USER:$OPENKM_PASS" \
  "$OPENKM_URL/services/rest/search/find?statement=SELECT%20*%20FROM%20nt%3Adocument%20LIMIT%201")

if [ "$HTTP_CODE" = "200" ]; then
    curl -s "$HEARTBEAT_URL"
else
    echo "Lucene search check failed: HTTP $HTTP_CODE"
fi

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

Schedule:

*/10 * * * * /usr/local/bin/openkm-search-check.sh

Step 6: Monitor the WebDAV Endpoint

OpenKM exposes a WebDAV interface at /OpenKM/webdav that allows users to mount the document repository as a network drive in Windows Explorer, macOS Finder, or any WebDAV-compatible client. A broken WebDAV endpoint disconnects all desktop clients.

1. In Vigilmon, click Add Monitor → HTTP / HTTPS.
2. Enter: http://your-server-ip:8080/OpenKM/webdav/okm%3Aroot/.
3. Set Expected HTTP status to 207 (WebDAV PROPFIND multi-status) or 401 (authentication required).
4. Set Check interval to 2 minutes.
5. Click Save.

A 401 response confirms WebDAV is serving requests even without providing credentials in the monitor — which is safe since you are verifying availability, not authentication. If your Vigilmon plan supports custom HTTP methods, use PROPFIND:

Method: PROPFIND
URL: http://your-server-ip:8080/OpenKM/webdav/
Headers: Depth: 0

Step 7: Monitor the REST API

OpenKM's REST API at /OpenKM/services/rest/ is the integration surface for custom applications, automation scripts, and third-party connectors. Verify the document list endpoint responds:

1. In Vigilmon, click Add Monitor → HTTP / HTTPS.
2. Enter: http://your-server-ip:8080/OpenKM/services/rest/document/list.
3. Set Expected HTTP status to 200 (if credentials are embedded) or 401 (unauthenticated — confirms the REST layer is up).
4. Set Check interval to 2 minutes.
5. Click Save.

For an authenticated check with richer validation:

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

RESPONSE=$(curl -s -m 10 \
  -u "${OPENKM_USER:-okmAdmin}:${OPENKM_PASS:-admin}" \
  "http://localhost:8080/OpenKM/services/rest/repository/info")

if echo "$RESPONSE" | grep -q "repositoryId"; then
    curl -s "$HEARTBEAT_URL"
fi

Schedule every 5 minutes:

*/5 * * * * /usr/local/bin/openkm-api-check.sh

Step 8: Monitor Tomcat Thread Pool Saturation

Tomcat maintains a thread pool for HTTP request handling. When all threads are busy — due to slow JCR operations, large document uploads, or blocking database queries — new requests queue and then time out. Thread exhaustion is a common OpenKM failure mode under load.

#!/bin/bash
# /usr/local/bin/openkm-threads-check.sh

HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_THREADS_HEARTBEAT_ID"
TOMCAT_JMX_PORT="${TOMCAT_JMX_PORT:-9010}"

# Query thread pool via JMX (requires JMX enabled in Tomcat)
THREAD_INFO=$(java -jar /opt/jmxterm.jar --url "service:jmx:rmi:///jndi/rmi://localhost:$TOMCAT_JMX_PORT/jmxrmi" \
  --non-interactive --input - <<EOF 2>/dev/null
bean Catalina:name="http-nio-8080",type=ThreadPool
get currentThreadsBusy
get maxThreads
EOF
)

BUSY=$(echo "$THREAD_INFO" | grep "currentThreadsBusy" | grep -oP '\d+' | tail -1)
MAX=$(echo "$THREAD_INFO" | grep "maxThreads" | grep -oP '\d+' | tail -1)

if [ -n "$BUSY" ] && [ -n "$MAX" ] && [ "$MAX" -gt 0 ]; then
    PCT=$(( BUSY * 100 / MAX ))
    if [ "$PCT" -lt 80 ]; then
        curl -s "$HEARTBEAT_URL"
    else
        echo "Thread pool at ${PCT}% saturation ($BUSY/$MAX)"
    fi
fi

If JMX is not available, use a simpler process-level check:

# Count Tomcat HTTP threads in WAITING state
BUSY_THREADS=$(jstack $(pgrep -f "catalina") 2>/dev/null | grep -c "http-nio-8080-exec" || echo 0)
echo "Tomcat HTTP threads active: $BUSY_THREADS"

Enable JMX in catalina.sh or setenv.sh:

JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote \
  -Dcom.sun.management.jmxremote.port=9010 \
  -Dcom.sun.management.jmxremote.authenticate=false \
  -Dcom.sun.management.jmxremote.ssl=false"

Step 9: Monitor JVM Heap Usage

Java OutOfMemoryError kills the Tomcat JVM and drops the entire OpenKM DMS. Heap pressure typically builds slowly during heavy document indexing or large file uploads. Monitor it before it reaches the fatal threshold.

#!/bin/bash
# /usr/local/bin/openkm-heap-check.sh

HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_HEAP_HEARTBEAT_ID"
HEAP_THRESHOLD=85  # Alert when heap usage exceeds 85%

TOMCAT_PID=$(pgrep -f "catalina" | head -1)

if [ -z "$TOMCAT_PID" ]; then
    echo "Tomcat process not found"
    exit 1
fi

# Get heap usage via jstat
HEAP_INFO=$(jstat -gc "$TOMCAT_PID" 2>/dev/null | tail -1)
if [ -n "$HEAP_INFO" ]; then
    # S0C S1C S0U S1U EC EU OC OU MC MU CCSC CCSU YGC YGCT FGC FGCT GCT
    S0C=$(echo "$HEAP_INFO" | awk '{print $1}')
    S1C=$(echo "$HEAP_INFO" | awk '{print $2}')
    EC=$(echo "$HEAP_INFO"  | awk '{print $5}')
    OC=$(echo "$HEAP_INFO"  | awk '{print $7}')
    S0U=$(echo "$HEAP_INFO" | awk '{print $3}')
    S1U=$(echo "$HEAP_INFO" | awk '{print $4}')
    EU=$(echo "$HEAP_INFO"  | awk '{print $6}')
    OU=$(echo "$HEAP_INFO"  | awk '{print $8}')

    TOTAL=$(echo "$S0C $S1C $EC $OC" | awk '{print $1+$2+$3+$4}')
    USED=$(echo "$S0U $S1U $EU $OU"  | awk '{print $1+$2+$3+$4}')
    PCT=$(echo "$USED $TOTAL" | awk '{printf "%d", ($1/$2)*100}')

    if [ "$PCT" -lt "$HEAP_THRESHOLD" ]; then
        curl -s "$HEARTBEAT_URL"
    else
        echo "JVM heap at ${PCT}% — above ${HEAP_THRESHOLD}% threshold"
    fi
fi

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

Schedule:

*/5 * * * * /usr/local/bin/openkm-heap-check.sh

Step 10: Monitor TLS Certificate Expiry

If OpenKM is accessed over HTTPS, an expired certificate locks out all users and breaks WebDAV mounts and REST API clients.

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 on the reverse proxy:

1. In Vigilmon, click Add Monitor → HTTP / HTTPS.
2. Enter: https://openkm.yourdomain.com/OpenKM/.
3. Enable Monitor SSL certificate with a 21 day alert threshold.
4. Set Check interval to 1 hour.
5. Click Save.

Step 11: 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 — Tomcat may take a few seconds to restart.
3. Set Consecutive failures before alert to 1 on the database and JCR monitors — a broken data layer means immediate outage.

Route failures by urgency:

• Tomcat down, JVM OOM, database unreachable → Slack #openkm-critical (immediate)
• JCR failure, Lucene index issue, thread pool saturation → Slack #openkm-alerts (urgent)
• WebDAV endpoint, TLS expiry → email (investigate within hours)

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI | GET /OpenKM/ | Tomcat or application startup failure | | Tomcat TCP | Port 8080 | JVM process crash | | Database | pg_isready / mysqladmin ping | Data layer unavailable | | Jackrabbit JCR | REST folder API | Document repository failure | | Lucene search | REST search API | Search index corruption or stall | | WebDAV | GET /OpenKM/webdav | Desktop client disconnection | | REST API | GET /services/rest/repository/info | Integration layer failure | | Thread pool | JMX currentThreadsBusy | Request queuing under load | | JVM heap | jstat -gc | OutOfMemoryError risk | | TLS certificate | HTTPS endpoint | Certificate expiry |

OpenKM's Java stack gives it broad enterprise capabilities, but Java process management — heap sizing, thread pool tuning, and Jackrabbit repository health — requires active monitoring. With Vigilmon watching every layer, a JVM heap spike or Jackrabbit stall alerts you before it becomes a DMS outage that blocks an entire department.