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
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 Standard URL
With SSL (Require)
With SSL (Verify CA)
With SSL (Verify Full)
Unix Socket
DATABASE_URL = postgres://username:password@hostname:5432/plausible_db
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
# 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.
Cookie Security # 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
Bamboo.Mua (Default)
SMTP Adapter
Postmark
Mailgun
SendGrid
Mandrill
Direct SMTP without relay (recommended for CE): MAILER_ADAPTER = Bamboo.Mua MAILER_EMAIL = [email protected] 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 = [email protected] 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 = [email protected] POSTMARK_API_KEY = your-postmark-api-key
Using Mailgun service: MAILER_ADAPTER = Bamboo.MailgunAdapter MAILER_EMAIL = [email protected] 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 = [email protected] SENDGRID_API_KEY = your-sendgrid-api-key
Using Mandrill service: MAILER_ADAPTER = Bamboo.MandrillAdapter MAILER_EMAIL = [email protected] MANDRILL_API_KEY = your-mandrill-api-key
Email Settings # From address (defaults to plausible@{BASE_URL host}) MAILER_EMAIL = [email protected] # 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:
MaxMind License (Recommended)
Custom Database File
GeoNames Source
# Automatically downloads and updates GeoLite2 database MAXMIND_LICENSE_KEY = your_license_key MAXMIND_EDITION = GeoLite2-City # Default
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
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
Standard Format
JSON Format
LOG_FORMAT = standard # Output: 2024-01-15 10:30:45 [info] 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://[email protected] /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 └── ...
# Path to additional Elixir config file EXTRA_CONFIG_PATH = /etc/plausible/extra_config.exs
Validation Checklist Next Steps
Upgrade Guide Learn how to upgrade Plausible CE
Maintenance Operations, backups, and monitoring