Configuration Reference - Plausible Analytics

Configuration Overview

Plausible CE is configured through environment variables set in the plausible-conf.env file. Configuration can also be loaded from files in /run/secrets for Docker Swarm secrets support.

All environment variables can optionally be read from files in the directory specified by CONFIG_DIR (defaults to /run/secrets).

Required Configuration

These settings must be configured for Plausible to start:

BASE_URL

The base URL where Plausible is accessible.

BASE_URL=https://analytics.yourdomain.com

Must start with http:// or https://. Include the port if non-standard (e.g., http://localhost:8000).

SECRET_KEY_BASE

Secret key for encrypting session data and other sensitive information.

SECRET_KEY_BASE=your-64-character-secret-key-here

Generate the key

openssl rand -base64 64

Add to config

Copy the generated string to plausible-conf.env

Keep secure

Never commit this value to version control or share publicly

Must be at least 32 bytes long. Changing this value will invalidate all existing sessions.

Database Configuration

PostgreSQL

DATABASE_URL=postgres://username:password@hostname:5432/plausible_db

DATABASE_URL=postgres://username:password@hostname:5432/plausible_db?sslmode=require

DATABASE_URL=postgres://username:password@hostname:5432/plausible_db?sslmode=verify-ca

DATABASE_URL=postgres://username:password@hostname:5432/plausible_db?sslmode=verify-full&sslrootcert=/path/to/ca.crt

DATABASE_URL=postgresql:///plausible_db?host=/var/run/postgresql

SSL Certificate

DATABASE_CACERTFILE=/path/to/ca-certificate.crt

Setting DATABASE_CACERTFILE automatically enables TLS for PostgreSQL connections.

ClickHouse

CLICKHOUSE_DATABASE_URL=http://plausible_events_db:8123/plausible_events_db

ClickHouse Performance Settings

# Flush interval for batched inserts (milliseconds)
CLICKHOUSE_FLUSH_INTERVAL_MS=5000

# Maximum buffer size before forcing flush (bytes)
CLICKHOUSE_MAX_BUFFER_SIZE_BYTES=100000

# Connection pool size for ingestion
CLICKHOUSE_INGEST_POOL_SIZE=5

# Default storage policy
CLICKHOUSE_DEFAULT_STORAGE_POLICY=default

ClickHouse SSL Configuration

# Path to CA certificate for ClickHouse TLS
CLICKHOUSE_CACERTFILE=/path/to/clickhouse-ca.crt

Server Configuration

Network Settings

# IP address to bind to (0.0.0.0 for all interfaces)
LISTEN_IP=127.0.0.1

# HTTP port
HTTP_PORT=8000
PORT=8000  # Alternative to HTTP_PORT

# HTTPS port (enables automatic TLS)
HTTPS_PORT=443

Setting HTTPS_PORT in Community Edition enables automatic TLS certificate management via Let’s Encrypt.

WebSocket URL

# Optional: Custom WebSocket URL for real-time updates
WEBSOCKET_URL=wss://analytics.yourdomain.com/socket

WebSocket host must match or be a subdomain of BASE_URL host.

# Set secure flag on cookies (auto-detected from BASE_URL scheme)
SECURE_COOKIE=true  # Use true for HTTPS, false for HTTP

Email Configuration

Plausible sends emails for reports, notifications, and user invitations.

Mailer Adapter

# Default mailer (Bamboo.Mua - direct SMTP)
MAILER_ADAPTER=Bamboo.Mua

Direct SMTP without relay (recommended for CE):

MAILER_ADAPTER=Bamboo.Mua
MAILER_EMAIL=plausible@yourdomain.com
MAILER_NAME=Plausible Analytics

# Optional: Use SMTP relay
SMTP_HOST_ADDR=smtp.example.com
SMTP_HOST_PORT=587
SMTP_USER_NAME=username
SMTP_USER_PWD=password
SMTP_HOST_SSL_ENABLED=false

# Middlebox compatibility mode for TLS 1.3
SMTP_MIDDLEBOX_COMP_MODE=false

Classic SMTP adapter:

MAILER_ADAPTER=Bamboo.SMTPAdapter
MAILER_EMAIL=plausible@yourdomain.com

SMTP_HOST_ADDR=mail.example.com
SMTP_HOST_PORT=25
SMTP_USER_NAME=username
SMTP_USER_PWD=password
SMTP_HOST_SSL_ENABLED=false
SMTP_RETRIES=2
SMTP_MX_LOOKUPS_ENABLED=true

Using Postmark service:

MAILER_ADAPTER=Bamboo.PostmarkAdapter
MAILER_EMAIL=plausible@yourdomain.com
POSTMARK_API_KEY=your-postmark-api-key

Using Mailgun service:

MAILER_ADAPTER=Bamboo.MailgunAdapter
MAILER_EMAIL=plausible@yourdomain.com
MAILGUN_API_KEY=your-mailgun-api-key
MAILGUN_DOMAIN=mg.yourdomain.com
MAILGUN_BASE_URI=https://api.mailgun.net/v3  # Optional

Using SendGrid service:

MAILER_ADAPTER=Bamboo.SendGridAdapter
MAILER_EMAIL=plausible@yourdomain.com
SENDGRID_API_KEY=your-sendgrid-api-key

Using Mandrill service:

MAILER_ADAPTER=Bamboo.MandrillAdapter
MAILER_EMAIL=plausible@yourdomain.com
MANDRILL_API_KEY=your-mandrill-api-key

Email Settings

# From address (defaults to plausible@{BASE_URL host})
MAILER_EMAIL=analytics@yourdomain.com

# From name
MAILER_NAME=Your Analytics Platform

Registration and Authentication

Registration Control

# Disable all registration
DISABLE_REGISTRATION=true

# Allow only invited users to register (CE default)
DISABLE_REGISTRATION=invite_only

# Allow anyone to register
DISABLE_REGISTRATION=false

Community Edition defaults to invite_only registration mode.

Email Verification

# Require email verification for new accounts
ENABLE_EMAIL_VERIFICATION=false  # Disabled by default

Two-Factor Authentication

# Optional: Custom TOTP vault key (32 bytes, base64 encoded)
TOTP_VAULT_KEY=$(openssl rand -base64 32)

If not set, TOTP vault key is derived from SECRET_KEY_BASE.

Geolocation

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

# Automatically downloads and updates GeoLite2 database
MAXMIND_LICENSE_KEY=your_license_key
MAXMIND_EDITION=GeoLite2-City  # Default

# Path to custom .mmdb file
IP_GEOLOCATION_DB=/etc/plausible/dbip-city.mmdb

# Custom GeoNames data file
GEONAMES_SOURCE_FILE=/path/to/geonames.tsv

Data Storage

Data Directories

# Primary data directory for exports, imports, and cache
DATA_DIR=/var/lib/plausible

# Alternative: Persistent cache directory
PERSISTENT_CACHE_DIR=/var/lib/plausible/cache

S3 Storage (Optional)

For CSV exports and imports using S3-compatible storage:

# Disable S3 (default: true)
S3_DISABLED=false

# S3 Configuration
S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
S3_REGION=us-east-1
S3_ENDPOINT=https://s3.amazonaws.com

# Bucket names
S3_EXPORTS_BUCKET=plausible-exports
S3_IMPORTS_BUCKET=plausible-imports

Using Cloudflare R2

S3_DISABLED=false
S3_ACCESS_KEY_ID=your_access_key
S3_SECRET_ACCESS_KEY=your_secret_key
S3_REGION=auto
S3_ENDPOINT=https://<ACCOUNT_ID>.r2.cloudflarestorage.com
S3_EXPORTS_BUCKET=plausible-exports
S3_IMPORTS_BUCKET=plausible-imports

Logging

# Log level: debug, info, notice, warning, error
LOG_LEVEL=warning  # Default for production

# Log format: standard or json
LOG_FORMAT=standard

# Log failed login attempts
LOG_FAILED_LOGIN_ATTEMPTS=false

LOG_FORMAT=standard
# Output: 2024-01-15 10:30:45 [info] Application started

LOG_FORMAT=json
# Output: {"time":"2024-01-15T10:30:45Z","level":"info","message":"Application started"}

Google Integration

For Google Search Console and Google Analytics imports:

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

Create OAuth Application

Go to Google Cloud Console and create OAuth 2.0 credentials

Set Redirect URI

Add {BASE_URL}/auth/google/callback as authorized redirect URI

Enable APIs

Enable Google Search Console API and Google Analytics API

Advanced Configuration

Admin Users

# Comma-separated list of user IDs with admin privileges
ADMIN_USER_IDS=1,2,3

Custom Script Name

# Change the tracking script filename
CUSTOM_SCRIPT_NAME=analytics  # Serves as /js/analytics.js

Background Jobs

# Disable cron jobs (not recommended)
DISABLE_CRON=false

Session Transfer

# Enable session transfer between versions (default: true in prod)
ENABLE_SESSION_TRANSFER=true

CAPTCHA (hCaptcha)

HCAPTCHA_SITEKEY=your-site-key
HCAPTCHA_SECRET=your-secret-key

Monitoring and Observability

# Sentry error tracking
SENTRY_DSN=https://public@sentry.io/project

# Honeycomb tracing
HONEYCOMB_API_KEY=your-api-key
HONEYCOMB_DATASET=plausible
OTLP_ENDPOINT=https://api.honeycomb.io:443

# Prometheus metrics (disabled by default in CE)
PROMEX_DISABLED=true

Environment

# Environment name for logging/monitoring
ENVIRONMENT=prod

# Application version
APP_VERSION=2.1.0

# Application host identifier
APP_HOST=analytics-server-01

TLS/HTTPS Configuration

Automatic TLS (Let’s Encrypt)

Community Edition supports automatic HTTPS certificate management:

# Enable HTTPS
HTTPS_PORT=443
HTTP_PORT=80  # Required for ACME validation

# Domain must be public and resolve to server
BASE_URL=https://analytics.yourdomain.com

# Optional: Custom ACME directory
ACME_DIRECTORY_URL=https://acme-v02.api.letsencrypt.org/directory

Domain must not be an IP address or localhost
Domain must be publicly accessible on port 80
DNS must point to your server

Import/Export Configuration

# Maximum buffer size for imports
IMPORTED_MAX_BUFFER_SIZE=10000

Configuration File Loading

From Files (Docker Secrets)

# Directory to read configuration files from
CONFIG_DIR=/run/secrets

Plausible will look for files named after environment variables:

/run/secrets/
├── BASE_URL
├── SECRET_KEY_BASE
├── DATABASE_URL
└── ...

Extra Elixir Configuration

# Path to additional Elixir config file
EXTRA_CONFIG_PATH=/etc/plausible/extra_config.exs

​Configuration Overview

​Required Configuration

​BASE_URL

​SECRET_KEY_BASE

​Database Configuration

​PostgreSQL

​SSL Certificate

​ClickHouse

​ClickHouse Performance Settings

​Server Configuration

​Network Settings

​WebSocket URL

​Cookie Security

​Email Configuration

​Mailer Adapter

​Email Settings

​Registration and Authentication

​Registration Control

​Email Verification

​Two-Factor Authentication

​Geolocation

​Data Storage

​Data Directories

​S3 Storage (Optional)

​Logging

​Google Integration

​Advanced Configuration

​Admin Users

​Custom Script Name

​Background Jobs

​Session Transfer

​CAPTCHA (hCaptcha)

​Monitoring and Observability

​Environment

​TLS/HTTPS Configuration

​Automatic TLS (Let’s Encrypt)

​Import/Export Configuration

​Configuration File Loading

​From Files (Docker Secrets)

​Extra Elixir Configuration

​Validation Checklist

​Next Steps

Upgrade Guide

Maintenance

Configuration Overview

Required Configuration

BASE_URL

SECRET_KEY_BASE

Database Configuration

PostgreSQL

SSL Certificate

ClickHouse

ClickHouse Performance Settings

Server Configuration

Network Settings

WebSocket URL

Cookie Security

Email Configuration

Mailer Adapter

Email Settings

Registration and Authentication

Registration Control

Email Verification

Two-Factor Authentication

Geolocation

Data Storage

Data Directories

S3 Storage (Optional)

Logging

Google Integration

Advanced Configuration

Admin Users

Custom Script Name

Background Jobs

Session Transfer

CAPTCHA (hCaptcha)

Monitoring and Observability

Environment

TLS/HTTPS Configuration

Automatic TLS (Let’s Encrypt)

Import/Export Configuration

Configuration File Loading

From Files (Docker Secrets)

Extra Elixir Configuration

Validation Checklist

Next Steps