tutorial

Picoshare Monitoring with Vigilmon

"Learn how to monitor Picoshare, the minimalist self-hosted file sharing service, with Vigilmon — covering web server uptime, file upload API availability, SQLite database health, share link generation service, expiration cleanup job, and guest upload endpoint response times."

Picoshare Monitoring with Vigilmon

Picoshare is a minimalist self-hosted file sharing service written in Go. It runs on port 4001, stores files and metadata in a single SQLite database, and provides simple shareable links with optional expiration dates. Teams use Picoshare for internal file distribution — sharing builds, assets, documents, or binary files without relying on cloud storage services. Because it is a single binary with no external dependencies beyond its SQLite database, it is often deployed on lightweight infrastructure where monitoring is easy to overlook.

Despite its simplicity, Picoshare is a dependency in workflows that rely on generated share links. A crashed server, a locked SQLite database, or a broken upload API silently breaks these workflows — callers receive no alert and files are not delivered.

This guide covers how to monitor Picoshare with Vigilmon.

Why Picoshare Needs Monitoring

Picoshare failures break file sharing workflows silently:

  • Go web server crash — the binary crashes or is OOM-killed; all share links return connection refused; anyone attempting to download shared files receives no file and no error message
  • File upload API failure — the upload endpoint returns 500 or hangs; automation that uploads files to Picoshare breaks silently; files appear queued but are never stored
  • SQLite database lock or corruption — concurrent write contention or filesystem issues corrupt the SQLite database; uploads appear to succeed but metadata is never stored, and share links 404
  • Share link generation failure — the service generates a share token but fails to persist it; the link is sent to recipients but returns 404 when accessed
  • Expiration cleanup job failure — the background goroutine that purges expired shares stops; storage grows unboundedly and eventually fills the disk, taking down the service
  • Guest upload endpoint unavailability — if guest uploads are enabled, the unauthenticated upload endpoint times out; external collaborators cannot upload files they have been invited to share

Vigilmon monitors all of these failure modes so your team is alerted before a Picoshare failure silently drops files.

Picoshare Architecture Overview

| Component | Default Port | Role | Monitoring Priority | |-----------|-------------|------|---------------------| | Picoshare Go binary | 4001 | Web server, API, and file serving | Critical | | SQLite database | Local file | File metadata and share link storage | Critical | | Expiration cleanup goroutine | Internal | Purge expired shares, manage disk | High | | Guest upload endpoint | 4001 (same) | Unauthenticated file uploads | Medium |

Monitor 1: Picoshare Web Server Availability

Monitor the Picoshare home page to confirm the Go binary is up and responding:

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

Test your endpoint:

curl -s http://your-picoshare-host:4001/ | grep -i "picoshare"
# Expected: HTML containing "PicoShare"

Monitor 2: Picoshare API Health

Picoshare exposes a health check endpoint that returns application status. A 200 response confirms the web server is routing and the SQLite database is accessible:

  1. Type: HTTP
  2. Name: Picoshare - Health Check
  3. URL: http://your-picoshare-host:4001/api/health
  4. Method: GET
  5. Expected status: 200
  6. Keyword check: ok
  7. Interval: 1 minute
curl -s http://your-picoshare-host:4001/api/health
# Expected: {"status":"ok"} (HTTP 200)

The health endpoint explicitly checks the SQLite database connection. If it returns 500, the database is locked or corrupt — a critical issue requiring immediate attention.

Monitor 3: File Upload API Availability

Monitor the upload endpoint to verify the file upload path is operational. An unauthenticated POST to this endpoint returns 401 (not 500), confirming the route is registered and the handler is active:

  1. Type: HTTP
  2. Name: Picoshare - Upload API
  3. URL: http://your-picoshare-host:4001/api/upload
  4. Method: POST
  5. Expected status: 401
  6. Interval: 2 minutes
curl -s -o /dev/null -w "%{http_code}" \
  -X POST http://your-picoshare-host:4001/api/upload
# Expected: 401 (unauthenticated — upload endpoint is functional)
# Error: 500 (server-side failure in the upload handler)

Monitor 4: Guest Upload Endpoint (If Enabled)

If you have configured guest upload links, monitor one to verify the unauthenticated upload path is functional for external collaborators:

  1. Type: HTTP
  2. Name: Picoshare - Guest Upload Endpoint
  3. URL: http://your-picoshare-host:4001/g/YOUR_GUEST_LINK_ID
  4. Method: GET
  5. Expected status: 200
  6. Interval: 5 minutes
curl -s -o /dev/null -w "%{http_code}" \
  http://your-picoshare-host:4001/g/YOUR_GUEST_LINK_ID
# Expected: 200 (guest upload page loads)

Replace YOUR_GUEST_LINK_ID with a long-lived guest upload link created in Picoshare. If guest uploads are not enabled, skip this monitor.

Monitor 5: SSL Certificate Alert

If Picoshare is exposed via a reverse proxy with HTTPS:

  1. Type: HTTP
  2. Name: Picoshare - 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: Picoshare File Upload and Download Heartbeat

An hourly end-to-end check authenticates to Picoshare, uploads a small test file, generates a share link, downloads it, and verifies the content. This confirms the full file sharing pipeline — upload, SQLite write, link generation, and download — is working:

Heartbeat Script

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

PICOSHARE_URL="http://your-picoshare-host:4001"
PICOSHARE_PASS="$PICOSHARE_HEARTBEAT_PASSWORD"
VIGILMON_HEARTBEAT="YOUR_HEARTBEAT_ID"
TEST_FILE=$(mktemp /tmp/picoshare-test-XXXX.txt)

echo "picoshare-heartbeat-$(date -u +%s)" > "$TEST_FILE"

# Step 1: Authenticate
AUTH_RESPONSE=$(curl -s -X POST \
  -H "Content-Type: application/json" \
  -d "{\"password\":\"${PICOSHARE_PASS}\"}" \
  "${PICOSHARE_URL}/api/auth")

TOKEN=$(echo "$AUTH_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tokenKey',''))" 2>/dev/null)

if [ -z "$TOKEN" ]; then
  echo "[picoshare-hb] Authentication failed"
  rm -f "$TEST_FILE"
  exit 1
fi

# Step 2: Upload a test file
UPLOAD_RESPONSE=$(curl -s -X POST \
  -H "X-Csrf-Token: $TOKEN" \
  --cookie "csrf_token=$TOKEN" \
  -F "file=@$TEST_FILE" \
  "${PICOSHARE_URL}/api/upload")

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

if [ -z "$FILE_ID" ]; then
  echo "[picoshare-hb] Upload failed: $UPLOAD_RESPONSE"
  rm -f "$TEST_FILE"
  exit 1
fi

# Step 3: Download the file and verify content
DOWNLOAD_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  "${PICOSHARE_URL}/api/share/${FILE_ID}/content")

if [ "$DOWNLOAD_STATUS" -ne 200 ]; then
  echo "[picoshare-hb] Download returned $DOWNLOAD_STATUS for file $FILE_ID"
  rm -f "$TEST_FILE"
  exit 1
fi

rm -f "$TEST_FILE"
echo "[picoshare-hb] Upload, link generation, and download all healthy"

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

Add to cron:

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

In Vigilmon:

  • Type: Heartbeat
  • Name: Picoshare - File Sharing Pipeline
  • Expected interval: 1 hour
  • Grace period: 10 minutes

A missed heartbeat means the full upload-download cycle has failed — share links are being sent to recipients but files are not accessible.

Alert Configuration

| Monitor | Type | Interval | Alert Channel | |---------|------|----------|---------------| | Web server | HTTP | 1 min | Slack + Email | | Health check (DB connectivity) | HTTP | 1 min | PagerDuty + Slack | | Upload API (401 check) | HTTP | 2 min | Slack | | Guest upload endpoint | HTTP | 5 min | Slack | | SSL certificate | HTTP | 1 hour | Email (21-day lead) | | File sharing pipeline | Heartbeat | 1 hour | PagerDuty + Email |

Use PagerDuty for the health check and heartbeat monitors. A SQLite lock or Go binary crash means all share links are broken — external recipients receive 404s or timeouts with no indication the service is down.

Status Page

  1. Status Pages → New Page → name it "Picoshare File Sharing"
  2. Add all monitors above
  3. Share with your team and operations contacts

When a recipient reports that a shared link is returning an error, this status page lets the sender immediately identify whether the issue is Picoshare-wide or specific to that link.

Summary

Picoshare is a lightweight but critical file-sharing dependency. Vigilmon keeps the full sharing pipeline monitored:

  • HTTP monitors for web server availability, SQLite-backed health check, upload API, and guest upload endpoint
  • SSL certificate monitoring with a 21-day lead time for HTTPS deployments
  • Hourly heartbeat that uploads a test file, generates a share link, and downloads it — confirming the full pipeline from upload to delivery is working

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