Plausible CE is configured with environment variables.

The environment variables listed on this page can be set in your [.env](https://docs.docker.com/compose/environment-variables/variable-interpolation/#env-file) file that was created during [quickstart.](https://github.com/plausible/community-edition/tree/v2.1.3#quick-start)

## 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.

```env
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:

```console
$ openssl rand -base64 48
GLVzDZW04FzuS1gMcmBRVhwgd4Gu9YmSl/k/TqfTUXti7FLBd7aflXeQDdwCj6Cz
```
```env
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:

```console
$ openssl rand -base64 32
dsxvbn3jxDd16az2QpsX5B8O+llxjQ2SJE2i5Bzx38I=
```
```env
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.](#email)

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

```console
$ 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](https://hexdocs.pm/ecto/Ecto.Repo.html#module-urls).

---

#### 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-integration)

#### GOOGLE_CLIENT_ID

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

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

---

#### GOOGLE_CLIENT_SECRET

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

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

### IP Geolocation

Plausible CE uses the country database created by [db-ip](https://db-ip.com/) 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](https://www.maxmind.com) services and [enable city-level geolocation.](./maxmind-integration)

---

#### 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](https://github.com/plausible/analytics/blob/b096057eef28f25f8223cb625dfd3303ffce521a/Dockerfile#L49) shipped within the container image.

---

#### GEONAMES_SOURCE_FILE

Default: [/app/lib/location-0.1.0/priv/geonames.lite.csv](https://github.com/plausible/location/blob/main/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](#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](./maxmind-integration) for integration instructions.

---

#### MAXMIND_EDITION

Default: `GeoLite2-City`

MaxMind database edition to use (only if [MAXMIND_LICENSE_KEY](#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](#smtp_host_addr) by default. Alternatively, you can use other [services](https://hexdocs.pm/bamboo/readme.html#available-adapters) such as Postmark, Mailgun, Mandrill or Send Grid to send emails.

[Here's](https://gist.github.com/ruslandoga/c94ce526231fb77930132aaeda3fc3c9) 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 <kbd>Bamboo.PostmarkAdapter</kbd>, <kbd>Bamboo.MailgunAdapter</kbd>, <kbd>Bamboo.MandrillAdapter</kbd> or <kbd>Bamboo.SendGridAdapter</kbd> 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](#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 <kbd>https://api.mailgun.net/v3</kbd>. To override this you can pass <kbd>https://api.eu.mailgun.net/v3</kbd> 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.

```env
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`):

```elixir
import Config

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

2. Create or update your [`compose.override.yml`](https://github.com/plausible/community-edition/wiki/Compose-Override) to mount this file into the container:

```yaml
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:

```console
$ 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.