Installation Guide

Choose between Plausible Cloud managed hosting or self-hosted Community Edition. Complete installation instructions for both options.

Choose Your Installation Method

Plausible Analytics offers two deployment options to fit your needs:

Plausible Cloud

Managed hosting - We handle everything: infrastructure, updates, backups, security, and scaling

Community Edition

Self-hosted - Complete control over your data and infrastructure, but you manage it all

Plausible Cloud (Recommended)

Our managed cloud service is the fastest way to get started with Plausible Analytics.

Why Choose Plausible Cloud?

2-Minute Setup

Start tracking in minutes with zero infrastructure management

Worldwide CDN

Fast script loading from edge locations around the world

High Availability

99.9% uptime with automated backups and disaster recovery

Always Updated

Get new features multiple times per week, automatically

Advanced Bot Filtering

Excludes ~32K data center IP ranges and sophisticated bot detection

Premium Support

Real support from the people who build Plausible

Cloud Installation Steps

1. Create Your Account

   Visit plausible.io/register and sign up for a free 30-day trial.

   No credit card required to start.

2. Add Your Website

   Enter your domain name (e.g., example.com) and configure your timezone.

3. Install the Tracking Script

   Choose your installation method:

   For standard websites:

   <!-- Privacy-friendly analytics by Plausible -->
   <script async src="https://plausible.io/js/YOUR-SCRIPT-ID.js"></script>
   <script>
     window.plausible=window.plausible||function(){(plausible.q=plausible.q||[]).push(arguments)},plausible.init=plausible.init||function(i){plausible.o=i||};
     plausible.init()
   </script>
   

   For NPM/JavaScript apps:

   npm install @plausible-analytics/tracker
   

   import { init } from '@plausible-analytics/tracker'
   
   init({ domain: 'example.com' })
   
4. Verify and Start Tracking

   Visit your website to generate a test pageview, then check your Plausible dashboard.

   Your analytics are now live!

Cloud-Only Premium Features

The following features are exclusive to Plausible Cloud:

• Marketing Funnels - Visualize conversion paths and optimize your funnel
• Ecommerce Revenue Goals - Track monetary value and ROI
• SSO (Single Sign-On) - Enterprise authentication integration
• Sites API - Programmatically manage multiple sites
• Priority Support - Direct support from the Plausible team

Pricing

Plausible Cloud uses volume-based pricing:

• Free trial: 30 days, no credit card required
• Starting at: $9/month for up to 10K monthly pageviews
• Scales with you: Pay only for what you use

View full pricing details at plausible.io/pricing

EU Data Residency - All visitor data is exclusively processed on EU-owned cloud infrastructure in Germany, ensuring GDPR compliance. Your data never leaves the EU.

---

Self-Hosted Community Edition

Plausible Community Edition (CE) is our free, open-source, self-hosted version.

Why Self-Host?

Full Control

Host on your own infrastructure, anywhere in the world

No Subscription

Free to use - only pay for your server costs

Direct Database Access

Query ClickHouse directly for raw analytics data

Open Source

AGPLv3 licensed - inspect, modify, and contribute to the code

Community Edition Differences

Community Edition has some important differences from Cloud:

Feature	Cloud	Community Edition
Release Schedule	Multiple updates per week	Twice per year (LTS releases)
Bot Filtering	Advanced (32K+ IP ranges)	Basic (User-Agent only)
Premium Features	✅ All included	❌ Not available
Support	Premium support team	Community forum only
Infrastructure	Fully managed	You manage everything

Self-Hosting Requirements

Self-hosting requires technical expertise in Docker, databases, and server administration.

Minimum System Requirements:

• CPU: 2+ cores recommended
• RAM: 4GB minimum (8GB+ recommended for production)
• Disk: 20GB+ (grows with data retention)
• Docker: Version 20.10 or newer
• Docker Compose: Version 2.0 or newer

Technology Stack:

• Elixir/Phoenix application
• PostgreSQL database (general data)
• ClickHouse database (analytics data)
• Node.js (for asset compilation)

Self-Hosted Installation

1. Clone the Repository

   git clone https://github.com/plausible/community-edition.git
   cd community-edition
   
2. Configure Environment Variables

   Copy the example configuration and customize it:

   cp plausible-conf.env.example plausible-conf.env
   

   Edit plausible-conf.env and set required variables:

   # Your domain where Plausible will be hosted
   BASE_URL=https://analytics.yourdomain.com
   
   # Generate a random secret key
   SECRET_KEY_BASE=your-secret-key-here
   
   # Database configuration (defaults are usually fine)
   # POSTGRES_PASSWORD=postgres
   # CLICKHOUSE_PASSWORD=clickhouse
   

   Generate a secure SECRET_KEY_BASE using: openssl rand -base64 64

3. Start the Services

   Use Docker Compose to start all services:

   docker compose up -d
   

   This will start:

   • Plausible application server
   • PostgreSQL database
   • ClickHouse analytics database
   • Mail server (for notifications)
4. Create Your Admin Account

   Visit your Plausible instance (e.g., http://localhost:8000 or your configured domain).

   Register your admin account and add your first website.

5. Configure Reverse Proxy (Production)

   For production deployments, configure a reverse proxy (nginx, Caddy, Traefik) with SSL:

   Example nginx configuration:

   server {
       listen 443 ssl http2;
       server_name analytics.yourdomain.com;
       
       ssl_certificate /path/to/cert.pem;
       ssl_certificate_key /path/to/key.pem;
       
       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;
           proxy_set_header X-Forwarded-Proto $scheme;
       }
   }
   
6. Install Tracking Script

   Update the tracking script to point to your self-hosted instance:

   <script async src="https://analytics.yourdomain.com/js/script.js"></script>
   <script>
     window.plausible=window.plausible||function(){(plausible.q=plausible.q||[]).push(arguments)},plausible.init=plausible.init||function(i){plausible.o=i||};
     plausible.init()
   </script>
   

   For the NPM package:

   init({
     domain: 'mywebsite.com',
     endpoint: 'https://analytics.yourdomain.com/api/event'
   })
   

Updating Community Edition

Community Edition releases are published twice per year. Always backup your data before upgrading.

1. Backup Your Data

   # Backup PostgreSQL
   docker compose exec postgres pg_dump -U postgres plausible_db > backup.sql
   
   # Backup ClickHouse (optional - can be regenerated)
   docker compose exec clickhouse clickhouse-client --query "BACKUP DATABASE plausible_events_db"
   
2. Pull Latest Changes

   git pull origin master
   
3. Rebuild and Restart

   docker compose down
   docker compose up -d --build
   
4. Run Migrations

   Migrations run automatically on startup. Check logs to verify:

   docker compose logs -f plausible
   

Self-Hosting Troubleshooting

Services won't start or keep crashing

Check the logs for specific errors:

docker compose logs -f

Common issues:

• Insufficient memory (increase Docker memory limit)
• Port conflicts (change ports in docker-compose.yml)
• Invalid SECRET_KEY_BASE (regenerate it)

ClickHouse database errors

ClickHouse requires significant memory. Ensure your host has at least 4GB RAM.

If ClickHouse won’t start:

docker compose down -v  # WARNING: This deletes all data
docker compose up -d

Email notifications not working

Configure SMTP settings in plausible-conf.env:

MAILER_EMAIL=[e-mail]
SMTP_HOST_ADDR=smtp.yourdomain.com
SMTP_HOST_PORT=587
SMTP_USER_NAME=your-smtp-username
SMTP_USER_PWD=your-smtp-password
SMTP_HOST_SSL_ENABLED=true

How do I import Google Analytics data?

Google Analytics import is a Cloud-only feature. For CE, you’ll need to:

1. Export your GA data
2. Manually transform it to Plausible’s schema
3. Import into ClickHouse directly

This is complex and not officially supported. Consider using Cloud if GA import is critical.

Installation Methods Comparison

Script Installation (All Platforms)

Best for: Static sites, traditional CMS, simple integrations

Pros:

• Simplest setup
• Works everywhere
• Automatic pageview tracking

Cons:

• May be blocked by ad blockers
• Limited customization

NPM Package Installation

Best for: React, Vue, Next.js, modern JavaScript frameworks

Installation:

npm install @plausible-analytics/tracker

Configuration:

import { init, track } from '@plausible-analytics/tracker'

init({
  domain: 'mywebsite.com',
  endpoint: 'https://plausible.io/api/event',  // or your self-hosted URL
  autoCapturePageviews: true,
  hashBasedRouting: false,
  outboundLinks: true,
  fileDownloads: true,
  formSubmissions: false,
  captureOnLocalhost: false
})

// Track custom events
track('Signup', { props: { plan: 'Pro' } })

// Track revenue
track('Purchase', { 
  revenue: { amount: 29.99, currency: 'USD' }
})

Pros:

• Full TypeScript support
• Programmatic control
• Works with SSR frameworks
• Custom event tracking built-in

Cons:

• Requires build step
• Manual initialization needed

SSR Frameworks: The tracker only works in browser environments. For Next.js, ensure init is called in a client component or useEffect.

WordPress Plugin

Best for: WordPress sites (obviously!)

Installation:

1. Install “Plausible Analytics” plugin from WordPress.org
2. Activate and configure with your domain
3. Done!

Pros:

• Zero code required
• Automatic integration
• WP-specific features

Cons:

• WordPress only

Google Tag Manager

Best for: Sites already using GTM, enterprise setups

Installation:

1. Get your Script ID from Plausible
2. Install the Plausible GTM template
3. Configure with your Script ID

Pros:

• Integrate with existing GTM setup
• No code changes needed
• Conditional loading possible

Cons:

• Requires GTM knowledge
• Extra dependency

Next Steps

Quick Start

Follow our quick start guide to see your first pageview

Track Custom Events

Set up goals and custom event tracking

API Documentation

Integrate Plausible with your applications

Community Forum

Get help from the Plausible community

Need Help Choosing? - For most users, Plausible Cloud is the best choice. It’s hassle-free, always updated, and supports the project’s development. Self-hosting is recommended only if you have specific compliance requirements or technical expertise.