tutorial

Gokapi Monitoring with Vigilmon

"Learn how to monitor Gokapi, the self-hosted lightweight file sharing server with download limits and expiration, with Vigilmon — covering web server availability, file upload API health, download limit enforcement, SQLite database connectivity, expiration cleanup job, S3/local storage backend health, and admin dashboard monitoring."

Gokapi Monitoring with Vigilmon

Gokapi is a self-hosted, lightweight file sharing server written in Go. It runs on port 53842 and provides a web UI for uploading files with configurable download limits and expiration dates. Files are stored locally or in an S3-compatible backend, tracked in a SQLite database, and served via time-limited download links. Teams and individuals self-host Gokapi to share files internally or externally without depending on third-party services like WeTransfer or Dropbox.

Because Gokapi generates time-sensitive download links, any service interruption means recipients cannot download files before those links expire — and the sender has no way to know the download failed. Silent SQLite failures, stalled cleanup jobs, or S3 connectivity issues compound over time without alerting anyone.

This guide covers how to monitor Gokapi with Vigilmon.

Why Gokapi Needs Monitoring

Gokapi failures affect file availability and data integrity:

  • Web server crash — the Go HTTP server on port 53842 stops responding; file uploads are blocked and existing download links return 502 errors, causing recipients to miss time-limited files
  • File upload API failure — the upload endpoint stops accepting multipart requests; the web UI appears to work but upload submissions silently fail or return error responses
  • Download limit enforcement failure — the download counter mechanism stops decrementing; files that should expire after N downloads remain accessible indefinitely, violating expected sharing policies
  • SQLite database failure — the SQLite database becomes locked or corrupt; file metadata is unreadable, downloads fail with 500 errors, and uploaded files accumulate without tracking records
  • Expiration cleanup job stall — the background job that deletes expired files and their storage objects stops running; storage grows unbounded and expired links continue serving files past their intended lifetime
  • S3 storage backend failure — the S3-compatible object store becomes unreachable; file uploads succeed at the API layer but the actual data is never written, leaving broken download links
  • Admin dashboard failure — the admin interface becomes inaccessible; operators cannot manage files, revoke links, or configure new uploads

Vigilmon monitors all of these failure modes so issues are caught before file recipients are affected.

Gokapi Architecture Overview

| Component | Default Port | Role | Monitoring Priority | |-----------|-------------|------|---------------------| | Gokapi web server | 53842 | Web UI, upload API, download serving | Critical | | Admin dashboard | 53842/admin | File management and configuration | High | | SQLite database | Local file | File metadata, download counts, expiry | Critical | | S3/local storage backend | External or local | Actual file object storage | High | | Expiration cleanup job | Internal (cron-like) | Deletes expired files and objects | Medium |

Monitor 1: Gokapi Web Server Availability

Monitor the Gokapi home page to confirm the Go HTTP server is up:

  1. Log in to Vigilmon → Monitors → New Monitor
  2. Type: HTTP
  3. Name: Gokapi - Web Server
  4. URL: http://your-gokapi-host:53842/
  5. Method: GET
  6. Expected status: 200
  7. Keyword check: Gokapi
  8. Interval: 1 minute

Test your endpoint:

curl -s http://your-gokapi-host:53842/ | grep -i "gokapi"
# Expected: HTML containing "Gokapi"

Monitor 2: Gokapi Admin Dashboard Availability

The admin interface requires authentication. An HTTP 200 on the login page confirms the admin routing layer is healthy, independent of user-facing file serving:

  1. Type: HTTP
  2. Name: Gokapi - Admin Dashboard
  3. URL: http://your-gokapi-host:53842/admin
  4. Method: GET
  5. Expected status: 200
  6. Keyword check: Admin
  7. Interval: 2 minutes
curl -s -o /dev/null -w "%{http_code}" http://your-gokapi-host:53842/admin
# Expected: 200 (login form served)
# Error: 500 or 502 (server failure)

Monitor 3: Gokapi Upload API Health

The upload API endpoint returns 405 (Method Not Allowed) for a plain GET request — this confirms the route is registered and the server is processing requests for this path:

  1. Type: HTTP
  2. Name: Gokapi - Upload API
  3. URL: http://your-gokapi-host:53842/upload
  4. Method: GET
  5. Expected status: 405
  6. Interval: 2 minutes
curl -s -o /dev/null -w "%{http_code}" http://your-gokapi-host:53842/upload
# Expected: 405 (route registered, only POST accepted)
# Error: 404 or 502 (route missing or server down)

Monitor 4: S3 Storage Backend Connectivity

If Gokapi is configured to use an S3-compatible backend (MinIO, Backblaze B2, AWS S3), monitor the storage endpoint to catch connectivity failures before uploads are silently lost:

  1. Type: HTTP
  2. Name: Gokapi - S3 Storage Backend
  3. URL: http://your-minio-host:9000/minio/health/live
  4. Method: GET
  5. Expected status: 200
  6. Interval: 5 minutes

For AWS S3, monitor the bucket endpoint:

curl -s -o /dev/null -w "%{http_code}" https://s3.amazonaws.com/your-bucket/
# Expected: 403 (bucket reachable but authentication required)
# Error: 000 or 503 (connectivity failure)

Monitor 5: SSL Certificate Alert

If Gokapi is exposed via a reverse proxy with HTTPS:

  1. Type: HTTP
  2. Name: Gokapi - SSL Certificate
  3. URL: https://share.your-domain.com/
  4. SSL certificate expiry alert: 21 days before expiry
  5. Interval: 1 hour
curl -vI https://share.your-domain.com/ 2>&1 | grep "expire date"
# Expected: a future expiry date with at least 21 days remaining

Monitor 6: Gokapi Upload and Download Pipeline Heartbeat

An hourly heartbeat uploads a small test file, verifies the download link works, and confirms the full upload-to-download pipeline is functional. This catches SQLite failures, storage backend disconnections, and link generation bugs simultaneously:

Heartbeat Script

#!/bin/bash
# gokapi-heartbeat.sh — run hourly via cron
set -euo pipefail

GOKAPI_URL="http://your-gokapi-host:53842"
GOKAPI_API_KEY="${GOKAPI_API_KEY}"  # set in Gokapi admin → API keys
VIGILMON_HEARTBEAT="YOUR_HEARTBEAT_ID"
TEST_FILE=$(mktemp /tmp/gokapi-test-XXXXXX.txt)

cleanup() {
  rm -f "$TEST_FILE"
}
trap cleanup EXIT

# Create a small test file
echo "gokapi-heartbeat-$(date -u +%Y%m%dT%H%M%S)" > "$TEST_FILE"

# Step 1: Upload the test file (1 download allowed, expires in 1 hour)
UPLOAD_RESPONSE=$(curl -s -X POST \
  -H "apikey: ${GOKAPI_API_KEY}" \
  -F "file=@${TEST_FILE}" \
  -F "allowedDownloads=1" \
  -F "expiryDays=0" \
  "${GOKAPI_URL}/api/files/add")

FILE_ID=$(echo "$UPLOAD_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin).get('FileInfo',{}).get('Id',''))" 2>/dev/null)

if [ -z "$FILE_ID" ]; then
  echo "[gokapi-hb] Upload failed or no file ID returned"
  exit 1
fi

echo "[gokapi-hb] Test file uploaded with ID: $FILE_ID"

# Step 2: Download the file via the generated link
DOWNLOAD_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  "${GOKAPI_URL}/d?id=${FILE_ID}")

if [ "$DOWNLOAD_STATUS" -ne 200 ]; then
  echo "[gokapi-hb] Download returned $DOWNLOAD_STATUS (expected 200)"
  exit 1
fi

echo "[gokapi-hb] Upload and download pipeline healthy"

# Step 3: Signal Vigilmon
curl -s "https://heartbeat.vigilmon.online/$VIGILMON_HEARTBEAT"

Add to cron:

# /etc/cron.d/gokapi-heartbeat
0 * * * * root /opt/gokapi/gokapi-heartbeat.sh >> /var/log/gokapi-heartbeat.log 2>&1

In Vigilmon:

  • Type: Heartbeat
  • Name: Gokapi - Upload and Download Pipeline
  • Expected interval: 1 hour
  • Grace period: 10 minutes

Alert Configuration

| Monitor | Type | Interval | Alert Channel | |---------|------|----------|---------------| | Web server | HTTP | 1 min | Slack + Email | | Admin dashboard | HTTP | 2 min | Slack | | Upload API | HTTP | 2 min | Slack | | S3 storage backend | HTTP | 5 min | Email | | SSL certificate | HTTP | 1 hour | Email (21-day lead) | | Upload and download pipeline | Heartbeat | 1 hour | PagerDuty + Email |

Use PagerDuty for the heartbeat monitor. A failed upload-to-download pipeline means file recipients are silently receiving broken links — this needs immediate response.

Status Page

  1. Status Pages → New Page → name it "Gokapi File Sharing"
  2. Add all monitors above
  3. Share with team members who send files via Gokapi

When a recipient reports that a download link is not working, they can check this page before the sender has to re-upload and re-share.

Summary

Gokapi is a simple but operationally sensitive file sharing service — broken download links expire and cannot be recovered without re-uploading. Vigilmon keeps the full pipeline healthy:

  • HTTP monitors for web server availability, admin dashboard, and upload API route health
  • S3 backend monitoring to catch storage connectivity failures before uploads are silently lost
  • SSL certificate monitoring with a 21-day lead time for HTTPS deployments
  • Hourly heartbeat that uploads a test file and downloads it to verify the full pipeline end-to-end

Get started at vigilmon.online.

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