**Installing Plausible Analytics on VPS

Backups and Maintenance

Setting up backups and regular maintenance is critically important for any production system, including Plausible Analytics.

What to Back Up

For Plausible Analytics, you need to regularly back up the following components:

• PostgreSQL Database: Contains Plausible user accounts, site settings, domains, and other meta-information. This is the most crucial part.
• ClickHouse Database: Stores all collected events (page views, unique visitors, etc.). Although Plausible can function without old ClickHouse data, restoring the full scope of analytics requires backing it up.
• Plausible Configuration Files: The docker-compose.yml file, .env, and the clickhouse/ folder.

Simple Auto-Backup Script

We will create a simple script that will dump databases and archive configuration files. For storing backups, it is recommended to use external storage, not the same server.

Create the file backup_plausible.sh in the directory /home/youruser/plausible/:

nano backup_plausible.sh

Insert the following content (replace YOUR_DOMAIN and DB_PASSWORD with your values):

#!/bin/bash

# Path to the Plausible directory
PLAUSIBLE_DIR="/home/youruser/plausible"
# Directory for storing backups on the server (temporary storage)
BACKUP_DIR="${PLAUSIBLE_DIR}/backups"
# Domain used for Plausible
YOUR_DOMAIN="analytics.yourdomain.com"

# Load environment variables
set -a
. "${PLAUSIBLE_DIR}/.env"
set +a

# Ensure the backup directory exists
mkdir -p "${BACKUP_DIR}"

TIMESTAMP=$(date +%Y%m%d%H%M%S)
BACKUP_FILE="${BACKUP_DIR}/plausible_backup_${TIMESTAMP}.tar.gz"

echo "Starting Plausible Analytics backup..."

# 1. PostgreSQL Backup
echo "Dumping PostgreSQL database..."
docker compose exec -T plausible_db pg_dump -U plausible -d plausible > "${BACKUP_DIR}/plausible_db_${TIMESTAMP}.sql"
if [ $? -eq 0 ]; then
  echo "PostgreSQL database successfully archived."
else
  echo "Error archiving PostgreSQL database."
  exit 1
fi

# 2. ClickHouse Backup (if data is large, you can use clickhouse-backup or other methods)
# For simplicity, we copy the data directory (stopping ClickHouse during copying)
echo "Backing up ClickHouse data (copying)..."
docker compose stop plausible_events_db
tar -czvf "${BACKUP_DIR}/plausible_events_db_data_${TIMESTAMP}.tar.gz" -C "${PLAUSIBLE_DIR}/plausible_events_db_data" .
docker compose start plausible_events_db
if [ $? -eq 0 ]; then
  echo "ClickHouse data successfully archived."
else
  echo "Error archiving ClickHouse data."
  exit 1
fi

# 3. Archiving configuration files
echo "Archiving configuration files..."
tar -czvf "${BACKUP_DIR}/plausible_configs_${TIMESTAMP}.tar.gz" \
  -C "${PLAUSIBLE_DIR}" docker-compose.yml .env clickhouse/
if [ $? -eq 0 ]; then
  echo "Configuration files successfully archived."
else
  echo "Error archiving configuration files."
  exit 1
fi

# 4. Combining all backups into a single tar.gz archive
echo "Creating a unified backup archive..."
tar -czvf "${BACKUP_FILE}" -C "${BACKUP_DIR}" plausible_db_${TIMESTAMP}.sql plausible_events_db_data_${TIMESTAMP}.tar.gz plausible_configs_${TIMESTAMP}.tar.gz
if [ $? -eq 0 ]; then
  echo "Unified backup archive created: ${BACKUP_FILE}"
else
  echo "Error creating unified archive."
  exit 1
fi

# Deleting intermediate files
rm "${BACKUP_DIR}/plausible_db_${TIMESTAMP}.sql"
rm "${BACKUP_DIR}/plausible_events_db_data_${TIMESTAMP}.tar.gz"
rm "${BACKUP_DIR}/plausible_configs_${TIMESTAMP}.tar.gz"

echo "Backup completed."

# Here you can add commands to upload the backup to remote storage
# For example, via rsync, scp, s3cmd, or Restic
# rsync -avz "${BACKUP_FILE}" user@remotehost:/path/to/remote/backups/
# s3cmd put "${BACKUP_FILE}" s3://your-s3-bucket/plausible/
# restic backup --repo /mnt/backup_repo "${BACKUP_FILE}"

Make the script executable:

chmod +x backup_plausible.sh

Where to Store Backups

Never store backups on the same server as the original data. If the server fails, you will lose both your data and your backups. Recommended storage locations:

• External S3-compatible storage: Cloud services such as AWS S3, DigitalOcean Spaces, Backblaze B2, or MinIO on another server. This is a reliable and scalable option.
• Separate VPS or dedicated server: You can use another, less powerful VPS to store backups using rsync, scp, or specialized tools like Restic or BorgBackup.
• Local computer: For very small projects, you can periodically download backups to your local computer.

For automatic upload to S3-compatible storage, you can use s3cmd or aws cli. For Restic:

# Install Restic
sudo apt install restic -y
# Initialize repository (run once)
restic init --repo s3:s3.eu-central-1.amazonaws.com/your-plausible-bucket --password-file /path/to/s3_password.txt
# Example backup command in the script:
# restic backup --repo s3:s3.eu-central-1.amazonaws.com/your-plausible-bucket "${BACKUP_FILE}" --password-file /path/to/s3_password.txt

Setting Up Cron for Automatic Backup

Add a task to Cron so that the script runs regularly (e.g., daily).

crontab -e

Add the following line to the end of the file so that the script runs daily at 3:00 AM:

0 3 * * * /home/youruser/plausible/backup_plausible.sh >> /var/log/plausible_backup.log 2>&1

Save and close. Ensure that the user youruser has all necessary permissions to execute the script and access Docker.

Updates: rolling vs. maintenance window

Regular software updates are important for security and gaining new features.

• OS Update: It is recommended to perform this once a month or when critical patches are released. Use sudo apt update && sudo apt upgrade -y.
• Docker Image Update: For Plausible, PostgreSQL, ClickHouse.
  • Rolling update (for Docker): You can periodically run docker compose pull to download new image versions, and then docker compose up -d. Docker will replace containers with new versions, preserving data. It is advisable to do this during periods of low load.
  • Maintenance window: For larger updates or when changing major versions of Plausible/PostgreSQL/ClickHouse, it is recommended to schedule a "maintenance window". This means you temporarily stop services, perform a backup, update docker-compose.yml (if image versions or configurations change), and then start them again.

Example of Docker Image Update:

cd /home/youruser/plausible
# Stop services
docker compose down
# Download latest image versions
docker compose pull
# Start services with updated images
docker compose up -d

Always check the official Plausible documentation for update recommendations before proceeding.

Troubleshooting + FAQ

This section compiles common issues that may arise during the installation and operation of Plausible Analytics, along with answers to frequently asked questions.

Plausible does not start or is inaccessible via domain

What to check:

1. DNS Records: Ensure that your domain (e.g., analytics.yourdomain.com) correctly points to your VPS's IP address. Use ping analytics.yourdomain.com.
2. Firewall Ports (UFW): Ensure that ports 80 (HTTP) and 443 (HTTPS) are open. Execute sudo ufw status verbose.
3. Docker Container Status: Verify that all Plausible, PostgreSQL, and ClickHouse containers are running and in a healthy state. Use docker compose ps in the Plausible directory.
4. Docker Container Logs: If a container fails to start, check its logs: docker compose logs plausible, docker compose logs plausible_db, docker compose logs plausible_events_db. Look for errors related to database connection, environment variables, or resource scarcity.
5. Caddy Status: Ensure that Caddy is running and not reporting errors. sudo systemctl status caddy and sudo journalctl -u caddy --no-pager. Verify that Caddy was able to obtain an SSL certificate.
6. Caddyfile Configuration: Verify that the domain in Caddyfile matches your domain and that proxying is configured to 127.0.0.1:8000.
7. .env Configuration: Ensure that BASE_URL in the Plausible .env file matches your domain with https://.

How to fix: Correct the corresponding DNS records, open ports in UFW, check and fix errors in .env, docker-compose.yml, or Caddyfile, then restart Docker Compose (docker compose down && docker compose up -d) or Caddy (sudo systemctl reload caddy).

Error "Database connection error" or "Plausible is unavailable"

What to check:

1. Plausible Logs: docker compose logs plausible. Look for messages related to connecting to PostgreSQL or ClickHouse.
2. PostgreSQL/ClickHouse Status and Logs: Ensure that the databases are running and healthy: docker compose ps. Check their logs: docker compose logs plausible_db, docker compose logs plausible_events_db.
3. DB Environment Variables: Ensure that DATABASE_URL and CLICKHOUSE_DATABASE_URL in the Plausible .env file are configured correctly, and that passwords match those specified for PostgreSQL and ClickHouse.

How to fix: Correct the passwords or URLs in .env, then restart the Plausible container (docker compose restart plausible). If the issue is with the databases, check their configuration and ensure they start successfully.

Password reset or registration emails are not being received

What to check:

1. SMTP Settings in .env: Ensure that all variables SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, SMTP_MAIL_FROM are configured correctly for your email provider.
2. Plausible Logs: docker compose logs plausible. Look for errors related to email sending.
3. Firewall: Ensure that the port used for SMTP (usually 587 or 465) is open for outbound connections from your VPS.

How to fix: Check the login credentials for the SMTP server. If you are unsure, refer to your email provider's documentation. After making changes in .env, restart the Plausible container (docker compose restart plausible).

What is the minimum VPS configuration suitable for this task?

For a minimal installation of Plausible Analytics with Docker, Caddy, and PostgreSQL, a VPS with 2 CPU cores, 4 GB RAM, and 80 GB SSD is recommended. This will be sufficient to handle traffic of several hundred thousand page views per month. It is important that the disk is SSD to ensure good database performance. With a significant increase in traffic or the addition of many sites, an increase in resources, primarily RAM and disk space, will be required.

What to choose — VPS or dedicated for this task?

For most users and projects, a VPS is the optimal choice. It offers sufficient performance, flexibility, and significantly lower cost compared to a dedicated server. A dedicated server should only be considered in cases of very high load (millions of page views per day), when maximum performance, complete physical isolation, or specific hardware configurations unavailable on a VPS are required. For typical use of Plausible Analytics, a VPS will provide more than enough resources and scaling capabilities.

How to update Plausible Analytics to a new version?

What to check:

1. Official Plausible Documentation: Always check the official Plausible Analytics GitHub repository for the latest versions and update instructions.
2. Changes in docker-compose.yml: New versions may require updating images (e.g., plausible/analytics:v2.1), adding new environment variables, or changes in the docker-compose.yml structure.

How to fix:

# Перейдите в директорию Plausible
cd /home/youruser/plausible

# Сделайте бэкап перед обновлением (крайне рекомендуется)
./backup_plausible.sh

# Отредактируйте docker-compose.yml, чтобы использовать новый образ Plausible
# Например, измените 'plausible/analytics:v2.0' на 'plausible/analytics:v2.1'
nano docker-compose.yml

# Загрузите новые образы
docker compose pull

# Остановите старые контейнеры и запустите новые
docker compose up -d

# Проверьте логи на предмет ошибок
docker compose logs plausible

If the update includes database migrations, Plausible usually performs them automatically on startup. Ensure that all containers are back in a healthy state.

Conclusions and Next Steps

Congratulations! You have successfully installed and configured Plausible Analytics on your VPS server using Docker, Caddy, and PostgreSQL. You now have a fully functional, private, and controlled web analytics system that does not collect personal data and provides full control over your information.

Your new Plausible Analytics instance is ready to go, providing you with valuable insights into your website visitors without compromising privacy. You have gained not only a tool but also experience in deploying a complex web application on your own server, which is a valuable skill for any developer or project owner.

Next Steps:

• Scaling: If your traffic significantly increases, consider increasing VPS resources (CPU, RAM, disk) or optimizing the Plausible/ClickHouse configuration.
• Monitoring: Set up a monitoring system (e.g., Prometheus + Grafana) to track the status of your VPS, Docker containers, and Plausible performance.
• Additional Features: Explore Plausible's capabilities, such as custom events, goals, and segmentation, to analyze user behavior in more depth.