Plausible Analytics is a lightweight, privacy-focused, and open-source web analytics tool designed to keep user data under your control. It’s an excellent choice for self-hosting because it eliminates reliance on third-party analytics platforms, offers GDPR compliance, and provides actionable insights without bloating your infrastructure. In this guide, we’ll cover installation, configuration, logging, backups, updates, and how to leverage Plausible’s unique features for customization.
Installing Plausible Analytics
📦 Docker/Docker Compose Setup
To quickly deploy Plausible Analytics, Docker Compose is the recommended method. Below is a docker-compose.yml file tailored for Plausible Analytics, complete with PostgreSQL and ClickHouse configurations.
version: '3.7'
services:
plausible:
image: plausible/analytics:latest
container_name: plausible
env_file:
- plausible.env
ports:
- "8000:8000"
depends_on:
- db
- events_db
restart: always
db:
image: postgres:13
container_name: plausible_db
environment:
POSTGRES_PASSWORD: yourpassword
POSTGRES_DB: plausible
POSTGRES_USER: plausible
volumes:
- plausible-db-data:/var/lib/postgresql/data
restart: always
events_db:
image: yandex/clickhouse-server:21.3.15.4
container_name: plausible_events_db
volumes:
- plausible-events-db-data:/var/lib/clickhouse
restart: always
volumes:
plausible-db-data:
plausible-events-db-data:
Save this file and deploy the stack with the following commands:
mkdir plausible-analytics && cd plausible-analytics
nano plausible.env # Create and configure environment variables
## Start the Docker containers
docker-compose up -d
🚀 Manual Installation
For those who prefer direct installation on a Linux server, here’s how to set up Plausible Analytics manually:
## Install dependencies
sudo apt update && sudo apt install -y curl wget postgresql postgresql-contrib
## Set up PostgreSQL
sudo -u postgres psql -c "CREATE USER plausible WITH PASSWORD 'yourpassword';"
sudo -u postgres psql -c "CREATE DATABASE plausible OWNER plausible;"
## Download and configure Plausible
curl -L https://github.com/plausible/analytics/releases/latest/download/plausible.tar.gz | tar -xz
cd plausible
nano config/config.exs # Adjust your Plausible configuration
## Start Plausible
bin/plausible start
Configuring Nginx as a Reverse Proxy
🌐 Nginx Configuration
Set up Nginx to forward traffic to Plausible Analytics. Create a new server block configuration file:
server {
server_name analytics.yourdomain.com;
location / {
proxy_pass http://localhost:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
listen [::]:80;
listen 80;
}
Save the file as /etc/nginx/sites-available/plausible and enable it:
sudo ln -s /etc/nginx/sites-available/plausible /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
🔒 SSL/TLS Setup
To secure your connection, generate an SSL certificate using Let’s Encrypt:
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d analytics.yourdomain.com
Automate certificate renewals:
sudo systemctl enable certbot.timer
Logging and Debugging Plausible Analytics
🗃️ Enabling Debug Logs
Edit the plausible.env file to enable debug-level logging:
LOG_LEVEL=debug
Restart the container for the changes to take effect:
docker-compose restart plausible
📄 Viewing Logs
Access logs to monitor Plausible Analytics:
## For Docker-based installations
docker logs plausible
## For manual installations
tail -f /path/to/plausible/logs/production.log
🛠️ Troubleshooting Common Issues
If something isn’t working, analyze error logs:
## Check Docker container health
docker ps --filter "name=plausible"
## Inspect Postgres logs
docker logs plausible_db
Backup and Restore
🗂️ File-Based Backups
Backup important files and configurations:
tar -cvzf plausible-backup.tar.gz plausible.env docker-compose.yml
🔄 Database Backups
Export PostgreSQL data:
docker exec plausible_db pg_dump -U plausible plausible > plausible_db_backup.sql
Restore the backup when needed:
docker exec -i plausible_db psql -U plausible plausible < plausible_db_backup.sql
Updating and Upgrading Plausible Analytics
⬆️ Updating Docker Images
Pull the latest version of Plausible:
docker-compose pull
docker-compose up -d
🛠️ Manual Updates
If you use a manual setup, download the updated release and redeploy:
curl -L https://github.com/plausible/analytics/releases/latest/download/plausible.tar.gz | tar -xz
bin/plausible upgrade
Leveraging Plausible Analytics’s Unique Features
🔧 Enabling APIs
Plausible includes an API for programmatic access. To use it, generate an API key in the settings and test it with curl:
curl -H "Authorization: Bearer YOUR_API_KEY" https://analytics.yourdomain.com/api/v1/stats
🌟 Advanced Configurations
Enable custom domains or integrations in the plausible.env file:
CUSTOM_DOMAIN=analytics.yourdomain.com
ENABLE_EMAIL_REPORTS=true
Apply the changes:
docker-compose restart plausible
Wrapping Up
This guide covered everything from installing Plausible Analytics to customizing its features. By self-hosting, you gain full control over your analytics stack, ensuring privacy and flexibility. Start implementing the steps above, and enjoy the power of privacy-first analytics right at your fingertips!
