← All articles

What to monitor

For a self-hosted Paperclip instance, the key things to watch:

1. Is the service running? — Paperclip process alive and responding
2. Is it out of disk space? — Common cause of mysterious failures
3. Is memory healthy? — OOM kills are hard to debug after the fact
4. Are there error spikes in logs? — Early warning for application issues
5. External uptime — Is the URL accessible from the internet?

Check 1: Systemd service health

The most basic check — is the Paperclip process running?

# Check status
systemctl status paperclip

# Set up automatic restart on failure
# (Should already be in your .service file)
# Restart=always
# RestartSec=10

systemd handles process restarts automatically. If Paperclip crashes, it restarts within 10 seconds. This covers the most common failure scenario.

Check 2: The health endpoint

Paperclip exposes a health check at /api/health:

curl -s http://localhost:3100/api/health
# Returns: {"status":"ok","version":"x.x.x","authReady":true,...}

A non-200 response or timeout means something's wrong.

Add a cron-based health check:

# Add to crontab (runs every 5 minutes)
crontab -e

# Add this line:
*/5 * * * * curl -sf http://localhost:3100/api/health > /dev/null || systemctl restart paperclip

This auto-restarts Paperclip if the health endpoint stops responding.

Check 3: Disk space monitoring

A full disk causes cryptic failures. Monitor it:

# Check disk usage
df -h

# Alert when over 85% full (cron, every hour)
0 * * * * USAGE=$(df / | awk 'NR==2 {print $5}' | tr -d '%'); if [ "$USAGE" -gt 85 ]; then echo "Disk at ${USAGE}% on $(hostname)" | mail -s "Disk Alert" you@example.com; fi

Or use a simpler approach with a Paperclip task:

# Script to log disk usage to a file
df -h >> /var/log/disk-usage.log

Common space consumers:

• /var/log — rotated by logrotate but can grow large
• /tmp — usually auto-cleaned
• /opt/paperclip/data — grows with use, backup and trim if needed
• ~/.npm — npm cache, safe to delete: npm cache clean --force

Check 4: Memory monitoring

# Check current memory
free -h

# Watch for OOM kills in the last 24 hours
journalctl --since "24 hours ago" | grep -i "oom\|killed process\|out of memory"

# Set up htop for interactive monitoring
apt install -y htop

For automated memory monitoring, install netdata (lightweight, free):

bash <(curl -Ss https://my-netdata.io/kickstart.sh) --non-interactive

# Access at: http://YOUR_SERVER_IP:19999

Netdata provides real-time CPU, memory, disk I/O, and network charts with minimal resource overhead.

Check 5: External uptime monitoring

UptimeRobot monitors your URL from multiple global locations and alerts you when it's down. Free tier includes 50 monitors with 5-minute intervals.

1. Sign up at uptimerobot.com
2. Click Add New Monitor
3. Configure:
   • Monitor Type: HTTP(s)
   • Friendly Name: Paperclip
   • URL: https://paperclip.yourdomain.com/api/health
   • Monitoring Interval: 5 minutes
4. Add alert contacts (email, Slack, etc.)

You'll get an email within 5 minutes of your instance going down.

Free alternatives: Better Stack (1-minute checks free), Freshping, StatusCake.

Check 6: Log monitoring

Paperclip logs go through systemd journald:

# View recent logs
journalctl -u paperclip -n 100 --no-pager

# Follow live
journalctl -u paperclip -f

# Errors only
journalctl -u paperclip -p err --since "1 hour ago"

# Specific time range
journalctl -u paperclip --since "2025-01-15 10:00" --until "2025-01-15 12:00"

Set up log rotation to prevent journal from growing unbounded:

# Limit journal size to 1 GB
sed -i 's/#SystemMaxUse=/SystemMaxUse=1G/' /etc/systemd/journald.conf
systemctl restart systemd-journald

Alerting on error spikes (optional)

If you want alerts when errors appear in logs:

# Install lnav for structured log viewing
apt install -y lnav

# Create a simple error monitor script
cat > /opt/paperclip/check-errors.sh << 'EOF'
#!/bin/bash
ERRORS=$(journalctl -u paperclip --since "5 minutes ago" -p err --no-pager | wc -l)
if [ "$ERRORS" -gt 5 ]; then
  echo "Paperclip: $ERRORS errors in last 5 min" | mail -s "Paperclip Error Alert" you@example.com
fi
EOF
chmod +x /opt/paperclip/check-errors.sh

# Run every 5 minutes
crontab -e
# Add: */5 * * * * /opt/paperclip/check-errors.sh

Monitoring on managed platforms

Railway: Built-in deployment logs and metrics in the dashboard. No additional setup needed.

Render: Metrics tab in your service dashboard. Add health check at /api/health for automatic restart on failure.

Fly.io: fly logs for real-time logs. fly status for instance health.

Minimal viable monitoring checklist

• [ ] Systemd Restart=always in service file
• [ ] UptimeRobot on /api/health with email alert
• [ ] df -h cron alert at 85% disk usage
• [ ] Weekly manual check: journalctl -u paperclip --since "1 week ago" -p err

This covers the 90% of issues that will affect a self-hosted Paperclip instance without significant complexity or cost.

This is an independent guide. Paperclip Hosting is not affiliated with the official Paperclip project. Guide steps are based on real deployments and are subject to change as the software evolves.