Skip to main content

​
Prerequisites

Before installing Plausible CE, ensure you have:

Docker

Docker Engine 20.10.0 or higher

Docker Compose

Docker Compose v2.0.0 or higher

Domain Name

A domain pointing to your server (for HTTPS)

Server Access

SSH access with root or sudo privileges

​
Quick Start with Docker

The recommended way to run Plausible CE is using the official Docker image with the Community Edition hosting repository.

​
Step 1: Clone the Repository

git clone https://github.com/plausible/community-edition
cd community-edition

​
Step 2: Generate Secret Keys

Plausible requires a secret key base for security. Generate one using: 
openssl rand -base64 64
Save this key securely - you’ll need it for the configuration file.

​
Step 3: Configure Environment Variables

Create a configuration file: 
cp plausible-conf.env.example plausible-conf.env
Edit plausible-conf.env with your settings:
plausible-conf.env
# Required: Your domain name
BASE_URL=https://analytics.yourdomain.com

# Required: Secret key base (minimum 32 bytes)
SECRET_KEY_BASE=your-generated-secret-key-here

# Database URLs (defaults work with docker-compose)
DATABASE_URL=postgres://postgres:postgres@plausible_db:5432/plausible_db
CLICKHOUSE_DATABASE_URL=http://plausible_events_db:8123/plausible_events_db
Never commit plausible-conf.env to version control - it contains sensitive credentials.

​
Step 4: Start the Services

1

Start Docker Compose

Launch all services in detached mode:
docker compose up -d
This starts:
  • Plausible web application
  • PostgreSQL database
  • ClickHouse database
  • Mail server (optional)
2

Create Database

Initialize the database schema:
docker compose exec plausible sh -c "/app/createdb.sh"
3

Run Migrations

Apply database migrations:
docker compose exec plausible sh -c "/app/migrate.sh"
4

Verify Installation

Check that all containers are running:
docker compose ps
All services should show as “running” or “healthy”.

​
Step 5: Access Your Instance

Open your browser and navigate to your configured BASE_URL. You should see the Plausible registration page.
By default, Community Edition only allows registration via invite. The first user can register directly on initial setup.

​
Docker Image Details

The official Plausible CE Docker image is built from Alpine Linux: 
FROM alpine:3.22.2

# Application runs as non-root user (UID 999)
USER 999

# Default ports
EXPOSE 8000

# Default data directory
VOLUME /var/lib/plausible

# Entry point
ENTRYPOINT ["/entrypoint.sh"]
CMD ["run"]

​
Image Features

  • Base Image: Alpine Linux 3.22.2
  • Runtime: Elixir 1.19.4 / Erlang 27.3.4.6
  • Build Environment: MIX_ENV=ce
  • Security: Runs as non-root user
  • Size: Optimized for minimal footprint

​
Advanced Installation Options

​
Custom Port Configuration

# In plausible-conf.env
HTTP_PORT=8000
LISTEN_IP=0.0.0.0

​
IPv6 Support

To enable IPv6: 
# In plausible-conf.env
LISTEN_IP=::
TCP connections automatically try IPv6 first with IPv4 fallback in CE.

​
Running with Arbitrary UID

The container supports running with custom UIDs: 
docker run --user 1000:1000 plausible/analytics:latest

​
Database Setup

​
PostgreSQL Configuration

The default configuration uses: 
DATABASE_URL=postgres://postgres:postgres@plausible_db:5432/plausible_db
For production, consider: 
DATABASE_URL=postgres://username:password@hostname:5432/database_name

​
ClickHouse Configuration

Default ClickHouse connection: 
CLICKHOUSE_DATABASE_URL=http://plausible_events_db:8123/plausible_events_db

# Adjust buffer settings for high-traffic sites
CLICKHOUSE_FLUSH_INTERVAL_MS=5000
CLICKHOUSE_MAX_BUFFER_SIZE_BYTES=100000
CLICKHOUSE_INGEST_POOL_SIZE=5

​
Reverse Proxy Setup

For production deployments, use a reverse proxy like Nginx or Caddy:

​
Nginx Configuration

server {
    listen 80;
    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;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

​
Caddy Configuration

analytics.yourdomain.com {
    reverse_proxy localhost:8000
}

​
Geolocation Database

Plausible includes a basic country-level geolocation database. For city-level data:
1

Get MaxMind License

Sign up for a free MaxMind GeoLite2 account at https://www.maxmind.com
2

Configure License Key

# In plausible-conf.env
MAXMIND_LICENSE_KEY=your_license_key_here
MAXMIND_EDITION=GeoLite2-City
3

Restart Plausible

docker compose restart plausible
Plausible will automatically download and update the GeoLite2 database.

​
Verification

After installation, verify your setup:

​
Troubleshooting

Check logs for specific errors:
docker compose logs plausible
Common issues:
  • Missing or invalid SECRET_KEY_BASE
  • Invalid BASE_URL format
  • Database connection failures
Verify database containers are healthy:
docker compose ps
docker compose logs plausible_db
docker compose logs plausible_events_db
Ensure databases are ready before starting Plausible.
Check:
  • Firewall rules allow traffic on configured port
  • LISTEN_IP is set to 0.0.0.0 or ::
  • BASE_URL matches your access URL
  • Reverse proxy configuration is correct

​
Next Steps

Configuration

Configure email, integrations, and advanced options

Maintenance

Learn about backups and monitoring

Build docs developers (and LLMs) love

Get started for freeTalk to us