Plausible CE is configured with environment variables.

The environment variables listed on this page can be set in your .env file that was created during quickstart.

Required

BASE_URL

Configures the base URL to use in link generation and Cross-Site WebSocket Hijacking (CSWSH) checks.

It doesn't have any defaults and needs to be provided.

BASE_URL=https://plausible.example.com

---

SECRET_KEY_BASE

Configures the secret used for sessions in the dashboard and for generating other secrets like TOTP Vault Key.

It doesn't have any defaults and needs to be provided. It needs to be at least 64 bytes long.

It can be generated with OpenSSL:

$ openssl rand -base64 48
GLVzDZW04FzuS1gMcmBRVhwgd4Gu9YmSl/k/TqfTUXti7FLBd7aflXeQDdwCj6Cz

SECRET_KEY_BASE=GLVzDZW04FzuS1gMcmBRVhwgd4Gu9YmSl/k/TqfTUXti7FLBd7aflXeQDdwCj6Cz

Warning

Don't use this exact value :)

Optional

Docker Secrets Support

Plausible CE supports Docker secrets for storing sensitive configuration values. This allows you to keep credentials and other secrets separate from your environment configuration.

CONFIG_DIR

Default: /run/secrets

This environment variable specifies the directory where Plausible will look for configuration files. When a file with the same name as an environment variable exists in this directory, the contents of that file will be used instead of the environment variable.

For example, if you have a file /run/secrets/SECRET_KEY_BASE containing your secret key, Plausible will use that value instead of looking for a SECRET_KEY_BASE environment variable.

Registration

TOTP_VAULT_KEY

Default: derived from SECRET_KEY_BASE using PBKDF2

Configures the secret used for encrypting TOTP secrets at rest using AES256-GCM.

It can be generated with OpenSSL:

$ openssl rand -base64 32
dsxvbn3jxDd16az2QpsX5B8O+llxjQ2SJE2i5Bzx38I=

TOTP_VAULT_KEY=dsxvbn3jxDd16az2QpsX5B8O+llxjQ2SJE2i5Bzx38I=

---

DISABLE_REGISTRATION

Default: invite_only

Restricts registration of new users. Possible values are true (full restriction), false (no restriction), and invite_only (only the invited users can register).

---

ENABLE_EMAIL_VERIFICATION

Default: false

When enabled, new users need to verify their email address by following a link delivered to their mailbox. You can find Plausible's SMTP configuration options under below.

If something went wrong you can run this command to verify all users in the database:

$ cd plausible-ce # or wherever you cloned this repo
$ docker compose exec plausible_db psql -U postgres -h localhost -d plausible_db -c "UPDATE users SET email_verified = true;"

Web

HTTP_PORT

Default: 8000

Configures the port to bind the listen socket for the HTTP web server.

---

HTTPS_PORT

Configures the port to bind the listen socket for the HTTPS web server.

Tip

If you set HTTP_PORT=80 and HTTPS_PORT=443, Plausible will try to issue (and keep up to date) TLS certificates from Let's Encrypt.

Database

Plausible uses PostgreSQL for storing user data and ClickHouse -- for analytics data.

The values of DATABASE_URL and CLICKHOUSE_DATABASE_URL are used to configure the database connections and must be in the format of Ecto.Repo :url parameter.

---

DATABASE_URL

Default: postgres://postgres:postgres@plausible_db:5432/plausible_db

Configures the URL for PostgreSQL database.

CLICKHOUSE_DATABASE_URL

Default: http://plausible_events_db:8123/plausible_events_db

Configures the URL for ClickHouse database.

Google

For step-by-step integration with Google see our wiki guide.

GOOGLE_CLIENT_ID

The Client ID from the Google API Console for your project.

GOOGLE_CLIENT_ID=140927866833-002gqg48rl4iku76lbkk0qhu0i0m7bia.apps.googleusercontent.com

---

GOOGLE_CLIENT_SECRET

The Client Secret from the Google API Console for your project.

GOOGLE_CLIENT_SECRET=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

IP Geolocation

Plausible CE uses the country database created by db-ip for enriching analytics data with visitor countries. The database is shipped within the container image and country data collection happens automatically.

Optionally, you can provide a different database. For example, you can use MaxMind services and enable city-level geolocation.

---

IP_GEOLOCATION_DB

Default: /app/lib/plausible-0.0.1/priv/geodb/dbip-country.mmdb.gz

This database is used to lookup GeoName IDs for IP addresses. If not set, defaults to the file shipped within the container image.

---

GEONAMES_SOURCE_FILE

Default: /app/lib/location-0.1.0/priv/geonames.lite.csv

This file is used to turn GeoName IDs into human readable strings for display on the dashboard. Defaults to the one shipped within the container image.

---

MAXMIND_LICENSE_KEY

If set, this environment variable takes precedence over IP_GEOLOCATION_DB and makes Plausible download (and keep up to date) a free MaxMind GeoLite2 MMDB of the selected edition. See our wiki guide for integration instructions.

---

MAXMIND_EDITION

Default: GeoLite2-City

MaxMind database edition to use (only if MAXMIND_LICENSE_KEY is set).

Email

Plausible CE sends transactional emails e.g. account activation, password reset. In addition, it sends non-transactional emails like weekly or monthly reports.

It uses SMTP with an optional relay by default. Alternatively, you can use other services such as Postmark, Mailgun, Mandrill or Send Grid to send emails.

Here's a short guide on using your Gmail account for email delivery.

MAILER_ADAPTER

Default: Bamboo.Mua

Instead of the default, you can replace this with Bamboo.PostmarkAdapter, Bamboo.MailgunAdapter, Bamboo.MandrillAdapter or Bamboo.SendGridAdapter and add the appropriate variables.

MAILER_EMAIL

Default: plausible@${hostname $BASE_URL}

The email id to use for as from address of all communications from Plausible.

MAILER_NAME

The display name for the sender. If not set, the sender would show up as the email address set in MAILER_EMAIL.

---

SMTP_HOST_ADDR

The host address of your SMTP relay. If not set, the SMTP client tries to send the email directly. For that to work and for the email not to end up in spam, your machine needs to be allowed to make outgoing connections to port 25 and your sender domain from MAILER_EMAIL needs to have some DNS records like SPF or DKIM set.

SMTP_HOST_PORT

Default: 587

The port of your SMTP relay.

SMTP_USER_NAME

The username/email in case SMTP auth is required on your SMTP relay.

SMTP_USER_PWD

The password in case SMTP auth is required on your SMTP relay.

SMTP_HOST_SSL_ENABLED

Default: false

Configures whether SMTPS (SMTP over SSL) is enabled for SMTP connection, e.g. when you use port 465.

---

POSTMARK_API_KEY

Enter your Postmark API key.

Note

You also have to set the MAILER_EMAIL variable which needs to be configured in PostmarkApps sender signatures.

---

MAILGUN_API_KEY

Enter your Mailgun API key.

MAILGUN_DOMAIN

Enter your Mailgun domain.

MAILGUN_BASE_URI

Default: https://api.mailgun.net/v3

Mailgun makes a difference in the API base URL between sender domains from within the EU and outside. By default, the base URL is set to https://api.mailgun.net/v3. To override this you can pass https://api.eu.mailgun.net/v3 if you are using an EU domain.

---

MANDRILL_API_KEY

Enter your Mandrill API key.

---

SENDGRID_API_KEY

Enter your SendGrid API key.

Advanced Configuration

EXTRA_CONFIG_PATH

Allows you to specify the path to an additional Elixir configuration file that will be imported and applied to your Plausible instance. This provides an escape hatch for configurations not covered by environment variables.

EXTRA_CONFIG_PATH=/app/my_config.exs

This is useful for advanced configuration needs, such as custom database settings, custom authentication mechanisms, or other specialized configurations.

Configuration Example

1. Create a custom configuration file (e.g., my_config.exs):

import Config

config :plausible, Plausible.Repo,
  after_connect: {Postgrex, :query!, ["SET search_path TO global_prefix", []]}

2. Create or update your compose.override.yml to mount this file into the container:

services:
  plausible:
    volumes:
      - ./my_config.exs:/app/my_config.exs
    environment:
      - EXTRA_CONFIG_PATH=/app/my_config.exs

3. Run your Docker Compose commands as usual:

$ docker compose up -d

Note

Using compose.override.yml instead of modifying the default compose.yml is recommended as it prevents merge conflicts when updating Plausible CE.

Warning

This is an advanced feature and should be used with caution. Incorrect configurations could prevent Plausible from starting properly or cause unexpected behavior.