Maintenance & Operations - Plausible Analytics

Daily Operations

Monitoring Container Health

Regularly check that all services are running:

# Check container status
docker compose ps

# Expected output: All services should be "Up" or "healthy"

Plausible
PostgreSQL
ClickHouse

docker compose logs plausible --tail=100 --follow

Watch for:

Application startup messages
Error logs
Request timeouts
Database connection issues

docker compose logs plausible_db --tail=100 --follow

Watch for:

Connection errors
Slow queries
Disk space warnings
Replication issues (if configured)

docker compose logs plausible_events_db --tail=100 --follow

Watch for:

Insert errors
Memory issues
Merge tree problems
Query timeouts

Health Check Endpoints

Plausible provides health check endpoints:

# Liveness probe - is the application running?
curl http://localhost:8000/api/system/health/live

# Readiness probe - is the application ready to serve traffic?
curl http://localhost:8000/api/system/health/ready

# Legacy health check (soft-deprecated)
curl http://localhost:8000/api/health

Use /api/system/health/live and /api/system/health/ready for Kubernetes probes and load balancers.

Backup Strategy

PostgreSQL Backups

Manual Backup

Create a full database dump:

docker compose exec plausible_db pg_dump -U postgres plausible_db > backup_$(date +%Y%m%d_%H%M%S).sql

Compressed Backup

For large databases:

docker compose exec plausible_db pg_dump -U postgres plausible_db | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz

Automated Backups

Add a cron job:

# Edit crontab
crontab -e

# Add daily backup at 2 AM
0 2 * * * cd /path/to/community-edition && docker compose exec -T plausible_db pg_dump -U postgres plausible_db | gzip > /backups/postgres/backup_$(date +\%Y\%m\%d).sql.gz

ClickHouse Backups

ClickHouse data is the largest component:

# Create backup using ClickHouse's native backup system
docker compose exec plausible_events_db clickhouse-client --query \
  "BACKUP DATABASE plausible_events_db TO Disk('backups', 'backup_$(date +%Y%m%d).zip')"

ClickHouse backups can be very large. Ensure you have sufficient disk space and consider backup retention policies.

Restore Procedures

PostgreSQL
ClickHouse

# Stop services
docker compose down

# Start only PostgreSQL
docker compose up -d plausible_db

# Wait for database to be ready
sleep 5

# Drop and recreate database
docker compose exec plausible_db psql -U postgres -c "DROP DATABASE IF EXISTS plausible_db;"
docker compose exec plausible_db psql -U postgres -c "CREATE DATABASE plausible_db;"

# Restore from backup
gunzip -c backup_20240115.sql.gz | docker compose exec -T plausible_db psql -U postgres plausible_db

# Start all services
docker compose up -d

# Stop services
docker compose down

# Start only ClickHouse
docker compose up -d plausible_events_db

# Restore from native backup
docker compose exec plausible_events_db clickhouse-client --query \
  "RESTORE DATABASE plausible_events_db FROM Disk('backups', 'backup_20240115.zip')"

# Start all services
docker compose up -d

Database Maintenance

PostgreSQL Maintenance

Vacuum Database

Reclaim storage and update statistics:

# Regular vacuum (doesn't lock tables)
docker compose exec plausible_db psql -U postgres plausible_db -c "VACUUM ANALYZE;"

# Full vacuum (locks tables, schedule during low traffic)
docker compose exec plausible_db psql -U postgres plausible_db -c "VACUUM FULL ANALYZE;"

Schedule monthly with cron:

0 3 1 * * cd /path/to/community-edition && docker compose exec -T plausible_db psql -U postgres plausible_db -c "VACUUM ANALYZE;"

Check Database Size

docker compose exec plausible_db psql -U postgres plausible_db -c \
  "SELECT pg_size_pretty(pg_database_size('plausible_db'));"

Monitor Connections

docker compose exec plausible_db psql -U postgres -c \
  "SELECT count(*) FROM pg_stat_activity;"

ClickHouse Maintenance

Optimize Tables

Manually trigger merges for better performance:

# Optimize events table
docker compose exec plausible_events_db clickhouse-client --query \
  "OPTIMIZE TABLE plausible_events_db.events_v2 FINAL"

# Optimize sessions table
docker compose exec plausible_events_db clickhouse-client --query \
  "OPTIMIZE TABLE plausible_events_db.sessions_v2 FINAL"

OPTIMIZE FINAL can be resource-intensive. Run during low-traffic periods.

Check Table Sizes

docker compose exec plausible_events_db clickhouse-client --query \
  "SELECT table, formatReadableSize(sum(bytes)) as size FROM system.parts WHERE database = 'plausible_events_db' AND active GROUP BY table ORDER BY sum(bytes) DESC"

Monitor Merges

docker compose exec plausible_events_db clickhouse-client --query \
  "SELECT * FROM system.merges"

Drop Old Partitions

For data retention (e.g., keep only 2 years):

# List partitions
docker compose exec plausible_events_db clickhouse-client --query \
  "SELECT partition, table FROM system.parts WHERE database = 'plausible_events_db' GROUP BY partition, table ORDER BY partition"

# Drop specific partition (CAUTION: This deletes data!)
docker compose exec plausible_events_db clickhouse-client --query \
  "ALTER TABLE plausible_events_db.events_v2 DROP PARTITION '202201'"

Dropping partitions permanently deletes data. Always backup first!

Log Management

View Logs

# All services
docker compose logs --tail=100 --follow

# Specific service
docker compose logs plausible --tail=100 --follow

# Since specific time
docker compose logs --since="2024-01-15T10:00:00" plausible

# Filter by pattern
docker compose logs plausible | grep ERROR

Log Rotation

Configure Docker logging driver in docker-compose.yml:

services:
  plausible:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Export Logs

# Export to file
docker compose logs --no-color > plausible_logs_$(date +%Y%m%d).log

# Export with timestamps
docker compose logs --timestamps --no-color > plausible_logs_$(date +%Y%m%d).log

Performance Monitoring

Resource Usage

# Real-time resource monitoring
docker stats

# Specific container
docker stats community-edition-plausible-1

Query Performance

PostgreSQL
ClickHouse

# Slow queries
docker compose exec plausible_db psql -U postgres plausible_db -c \
  "SELECT query, calls, mean_exec_time FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;"

# Recent queries
docker compose exec plausible_events_db clickhouse-client --query \
  "SELECT query, query_duration_ms FROM system.query_log WHERE type = 'QueryFinish' ORDER BY query_start_time DESC LIMIT 10"

# Slow queries
docker compose exec plausible_events_db clickhouse-client --query \
  "SELECT query, query_duration_ms FROM system.query_log WHERE type = 'QueryFinish' AND query_duration_ms > 1000 ORDER BY query_duration_ms DESC LIMIT 10"

Cleanup and Optimization

Docker Cleanup

# Remove unused images
docker image prune -a

# Remove unused volumes (CAUTION: Can delete data!)
docker volume prune

# Remove all unused data
docker system prune -a --volumes

docker volume prune will delete all unused volumes, including database volumes if containers are stopped. Always verify volumes before pruning.

Clean Old Data

Session Cleanup

Plausible automatically cleans old user sessions every 2 hours via cron jobs.

Invitation Cleanup

Old invitations are cleaned daily at 1 AM.

Analytics Data

Manually archive or delete old analytics data:

# Export old data before deletion
docker compose exec plausible_events_db clickhouse-client --query \
  "SELECT * FROM plausible_events_db.events_v2 WHERE timestamp < '2022-01-01' FORMAT Native" > old_events.native

# Delete old data
docker compose exec plausible_events_db clickhouse-client --query \
  "ALTER TABLE plausible_events_db.events_v2 DELETE WHERE timestamp < '2022-01-01'"

Security Maintenance

Update Docker Images

Regularly update base images for security patches:

# Pull latest images
docker compose pull

# Recreate containers
docker compose up -d

Review Access Logs

# Check for suspicious activity
docker compose logs plausible | grep "401\|403\|404"

# Failed login attempts (if LOG_FAILED_LOGIN_ATTEMPTS=true)
docker compose logs plausible | grep "Failed login"

Rotate Secrets

Rotating SECRET_KEY_BASE will invalidate all user sessions. Plan accordingly.

Generate New Secret

openssl rand -base64 64

Update Configuration

Edit plausible-conf.env with the new secret

Restart Services

docker compose down
docker compose up -d

Notify Users

All users will need to log in again

Troubleshooting

High Memory Usage

Symptoms: Containers consuming excessive RAMSolutions:

Check ClickHouse memory settings
Reduce CLICKHOUSE_INGEST_POOL_SIZE
Optimize queries
Add more RAM or enable swap
Review max_memory_usage in ClickHouse config

Disk Space Issues

Symptoms: “No space left on device” errorsSolutions:

Check disk usage: df -h
Clean Docker: docker system prune -a
Clean old logs
Archive old analytics data
Optimize ClickHouse tables
Add more storage

Database Connection Errors

Symptoms: Cannot connect to PostgreSQL or ClickHouseSolutions:

Check database container status
Verify DATABASE_URL and CLICKHOUSE_DATABASE_URL
Check network connectivity
Review database logs
Restart database containers
Verify credentials

Slow Dashboard Performance

Symptoms: Dashboard takes long to loadSolutions:

Optimize ClickHouse tables: OPTIMIZE TABLE ... FINAL
Check for slow queries in ClickHouse logs
Increase ClickHouse memory allocation
Review and optimize custom goals
Consider archiving very old data
Check server resources (CPU, RAM, disk I/O)

Email Not Sending

Symptoms: Invites and reports not deliveredSolutions:

Check MAILER_ADAPTER configuration
Verify SMTP credentials

Test email configuration:

docker compose exec plausible sh -c "/app/bin/plausible eval 'Plausible.Mailer.send_test_email(\"[email protected]\")'"

Review mailer logs
Check firewall rules for SMTP ports
Verify DNS records (SPF, DKIM)

Monitoring Setup

Prometheus Metrics (Optional)

PromEx is disabled by default in Community Edition. Enable it for Prometheus monitoring.

# In plausible-conf.env
PROMEX_DISABLED=false

Metrics will be available at http://localhost:8000/metrics.

External Monitoring

Set up external monitoring for production:

Uptime Monitoring

Use services like UptimeRobot or Pingdom to monitor /api/system/health/live

Log Aggregation

Forward logs to services like Loki, ELK, or Datadog

Error Tracking

Configure Sentry for application error tracking with SENTRY_DSN

Metrics

Use Prometheus + Grafana for detailed metrics and dashboards

Maintenance Checklist

Daily
Weekly
Monthly
Quarterly

Getting Help

GitHub Discussions

Community support forum for self-hosting issues

Documentation

Official Community Edition documentation

Issue Tracker

Report bugs and feature requests

Changelog

Review changes and known issues

Next Steps

Configuration

Review and optimize your configuration

Upgrade Guide

Plan your next upgrade

Getting Started

Core Features

Integration

Self-Hosting

Advanced

​Daily Operations

​Monitoring Container Health

​Health Check Endpoints

​Backup Strategy

​PostgreSQL Backups

​ClickHouse Backups

​Restore Procedures

​Database Maintenance

​PostgreSQL Maintenance

​ClickHouse Maintenance

​Log Management

​View Logs

​Log Rotation

​Export Logs

​Performance Monitoring

​Resource Usage

​Query Performance

​Cleanup and Optimization

​Docker Cleanup

​Clean Old Data

​Security Maintenance

​Update Docker Images

​Review Access Logs

​Rotate Secrets

​Troubleshooting

​Monitoring Setup

​Prometheus Metrics (Optional)

​External Monitoring

Uptime Monitoring

Log Aggregation

Error Tracking

Metrics

​Maintenance Checklist

​Getting Help

GitHub Discussions

Documentation

Issue Tracker

Changelog

​Next Steps

Configuration

Upgrade Guide

Build docs developers (and LLMs) love

Daily Operations

Monitoring Container Health

Health Check Endpoints

Backup Strategy

PostgreSQL Backups

ClickHouse Backups

Restore Procedures

Database Maintenance

PostgreSQL Maintenance

ClickHouse Maintenance

Log Management

View Logs

Log Rotation

Export Logs

Performance Monitoring

Resource Usage

Query Performance

Cleanup and Optimization

Docker Cleanup

Clean Old Data

Security Maintenance

Update Docker Images

Review Access Logs

Rotate Secrets

Troubleshooting

Monitoring Setup

Prometheus Metrics (Optional)

External Monitoring

Maintenance Checklist

Getting Help

Next Steps