Plausible Analytics Deployment and Usage Guide

1. Prerequisites

Before deploying Plausible Analytics, ensure you have the following installed:

Runtime and Database:

• Elixir 1.15+ and Erlang/OTP 25+
• PostgreSQL 12+ (for primary database)
• ClickHouse 22.3+ (for analytics data storage)
• Node.js 18+ (for frontend assets)

Tools:

• Git
• Mix (Elixir's build tool, comes with Elixir)
• npm or yarn

Optional but Recommended:

• Docker and Docker Compose (for simplified deployment)
• SSL certificate (for production deployment)
• Domain name

2. Installation

Clone the repository and set up the project:

# Clone the repository
git clone https://github.com/plausible/analytics.git
cd analytics

# Install Elixir dependencies
mix deps.get

# Install JavaScript dependencies
npm install --prefix assets

# Set up database (requires running PostgreSQL instance)
mix ecto.setup

# Set up ClickHouse (requires running ClickHouse instance)
mix clickhouse.setup

For a quick start using Docker Compose:

# Use the provided docker-compose.yml
docker-compose up -d

3. Configuration

Create a .env file in the project root with the following environment variables:

Required Configuration:

# Database configuration
DATABASE_URL=postgres://postgres:password@localhost:5432/plausible
CLICKHOUSE_DATABASE_URL=http://localhost:8123/plausible

# Application secrets (generate with: mix phx.gen.secret)
SECRET_KEY_BASE=your_generated_secret_key_here
BASE_URL=http://localhost:8000

# Email configuration (for user registration and notifications)
MAILER_EMAIL=notifications@yourdomain.com
SMTP_HOST_ADDR=smtp.mailprovider.com
SMTP_HOST_PORT=587
SMTP_USER_NAME=username
SMTP_USER_PWD=password
SMTP_HOST_SSL=yes

Optional Configuration:

# Admin user (auto-created on first run)
ADMIN_USER_EMAIL=admin@example.com
ADMIN_USER_NAME=Admin
ADMIN_USER_PWD=secure_password

# Feature flags
DISABLE_REGISTRATION=false  # Set to true to disable new user registration
ENABLE_EMAIL_VERIFICATION=true

# Analytics script configuration
SCRIPT_CROSS_ORIGIN=anonymous
DISABLE_AUTOPLAY=false

Dashboard-specific settings (from source files):

• Dashboard periods are configured in dashboard-time-periods.ts (realtime, day, month, 7d, 24h, 28d, 30d, 91d, 6mo, 12mo, year, all, custom)
• Filter storage uses domain-scoped keys via getDomainScopedStorageKey()
• URL parameters for filters use FILTER_URL_PARAM_NAME="f" and labels use LABEL_URL_PARAM_NAME="l"

4. Build & Run

Development mode:

# Start PostgreSQL and ClickHouse services
docker-compose up -d db clickhouse

# Set up databases
mix ecto.setup
mix clickhouse.setup

# Start the Phoenix server with hot-reload
mix phx.server

The application will be available at http://localhost:8000.

Production build:

# Install production dependencies
MIX_ENV=prod mix deps.get --only prod

# Compile assets
npm run deploy --prefix assets

# Compile Elixir code
MIX_ENV=prod mix compile

# Digest static files
MIX_ENV=prod mix phx.digest

# Create database and run migrations
MIX_ENV=prod mix ecto.setup

# Start the server
MIX_ENV=prod mix phx.server

5. Deployment

Recommended Platforms:

1. Docker Deployment (Simplest):

   # Build and run with Docker Compose
   docker-compose -f docker-compose.yml up -d
   

2. Fly.io (Official recommended platform):

   # Install flyctl
   # Deploy using the provided fly.toml
   fly deploy
   

3. Railway/Render/Heroku:

   • Use the Elixir buildpack
   • Set all required environment variables
   • Add PostgreSQL and ClickHouse addons

4. Self-hosted VPS:

   • Set up Nginx/Apache as reverse proxy
   • Configure SSL with Let's Encrypt
   • Set up systemd service for automatic restarts
   • Configure backups for PostgreSQL and ClickHouse

Production considerations:

• Use a CDN for the tracking script (stored in priv/static/js/)
• Configure proper firewall rules
• Set up monitoring (Prometheus metrics available at /metrics)
• Implement regular backup strategy
• Use environment-specific configuration files

6. Troubleshooting

Common Issues and Solutions:

1. Database connection errors:

   # Verify PostgreSQL is running
   pg_isready -h localhost -p 5432
   
   # Verify ClickHouse is accessible
   curl http://localhost:8123/
   
   # Reset databases if needed
   mix ecto.reset
   mix clickhouse.reset
   

2. Asset compilation failures:

   # Clear npm cache
   npm cache clean --force --prefix assets
   
   # Reinstall dependencies
   rm -rf assets/node_modules
   npm install --prefix assets
   

3. ClickHouse migration issues:

   # Check ClickHouse logs
   docker-compose logs clickhouse
   
   # Run migrations manually
   mix clickhouse.migrate
   

4. Dashboard not loading/React errors:

   • Check browser console for JavaScript errors
   • Verify all environment variables are set correctly
   • Clear browser cache and localStorage (dashboard uses getDomainScopedStorageKey() for storage)

5. Email delivery problems:

   • Verify SMTP settings in environment variables
   • Check spam folder
   • Test with a local SMTP server like MailHog during development

6. Performance issues:

   • Monitor ClickHouse disk usage (analytics data grows quickly)
   • Consider partitioning tables by date
   • Implement caching for frequently accessed data

7. Upgrade issues:

   # Always backup before upgrading
   mix ecto.backup
   
   # Run migrations in order
   mix ecto.migrate
   mix clickhouse.migrate
   

Getting Help:

• Check the official documentation: https://plausible.io/docs
• Review GitHub issues: https://github.com/plausible/analytics/issues
• Join the community forum for support