Configuration options

When running a Plausible release, the following configuration parameters can be supplied as environment variables.

Default User Generation

A default user can be generated using the db init-admin command. In the default docker-compose setup, this command is run automatically when you boot the server.

It is highly recommended that you configure these parameters.

ParameterDefaultDescription
ADMIN_USER_NAMEautogeneratedAdmin user's name
ADMIN_USER_EMAILautogeneratedThe default ("admin") user email
ADMIN_USER_PWDautogeneratedThe default ("admin") user password.

Server

Following are the variables that can be used to configure the availability of the server.

ParameterDefaultDescription
BASE_URLhttp://localhost:8000The hosting url of the server, used for URL generation. In production systems, this should be your ingress host.
PORT8000The port on which the server is available.
SECRET_KEY_BASE--An internal secret key used by Phoenix Framework. Follow the instructions to generate one.
DISABLE_AUTHfalseDisables authentication completely, no registration, login will be shown.
DISABLE_REGISTRATIONfalseDisables registration of new users, keep your admin credentials handy ;)

Database

Plausible uses PostgreSQL for storing user data and ClickhouseDB for analytics data. Use the following variables to configure it.

ParameterDefaultDescription
DATABASE_URLpostgres://localhost:5432/plausible_devThe database URL as dictated here
CLICKHOUSE_DATABASE_URLhttp://localhost:8123/plausible_devConnection string for Clickhouse in the same format

Mailer/SMTP Setup

Plausible uses and SMTP server to send transactional emails e.g. account activation, password reset, weekly reports, etc.

ParameterDefaultDescription
MAILER_EMAILhello@plausible.localThe email id to use for as from address of all communications from Plausible.
SMTP_HOST_ADDRlocalhostThe host address of your smtp server.
SMTP_HOST_PORT25The port of your smtp server.
SMTP_USER_NAME--The username/email in case SMTP auth is enabled.
SMTP_USER_PWD--The password in case SMTP auth is enabled.
SMTP_HOST_SSL_ENABLEDfalseIf SSL is enabled for SMTP connection
SMTP_RETRIES2Number of retries to make until mailer gives up.

Alternatively, you can use Postmark to send transactional emails. In this case, use the following parameters:

ParameterDefaultDescription
MAILER_ADAPTERBamboo.SMTPAdapterInstead of the default, replace this with Bamboo.PostmarkAdapter
POSTMARK_API_KEY--Enter your API key.

IP Geolocation

Plausible uses the GeoLite2 database created by MaxMind for enriching analytics data with visitor countries. Their end-user license does not make it very easy to just package the database along with an open-source product. This is why, if you want to get country data for your analytics, you need to create an account and download their GeoLite2 Country database.

Once you have the database, mount it on the Plausible docker image and configure the path of the database file:

ParameterDefaultDescription
GEOLITE2_COUNTRY_DB--Path to your IP geolocation database in MaxMind's format

To make this as easy as possible you can use the maxmindinc/geoipupdate Docker image. You just need to add your account details, mount the database in the plausible container and let the image update the database automatically. To run the complete setup including geoip see docker-compose-geoip.yml.

If the Geolite database is not configured, no country data will be captured.

Google Search Integration

To enable the Google Search Console integration in Plausible Analytics, you need to authorize your self-hosted installation with a Google Account. For the OAuth flow, you need to configure the client_id and client_secret. Visit the Google API Console to obtain OAuth 2.0 credentials such as a client ID and client secret that are known to both Google and your installation. Once on the API Console, create a new project. On the project go to the "Credentials" screen and your installation's public URL followed by /auth/google/callback as "Authorized redirect URI".

Copy the client ID and Secret into these config values:

ParameterDefaultDescription
GOOGLE_CLIENT_ID--The Client ID from the Google API Console for your Plausible Analytics project
GOOGLE_CLIENT_SECRET--The Client Secret from the Google API Console for your Plausible Analytics project

After deploying those values, you can follow the Search Console Integration docs for the rest of the set up. For the final step of choosing a property from the Search Console, you also need to enable the "Google Search Console API (Legacy)" on your Google API project.

Twitter Integration

To automatically display tweets that link to your sites, you need a Twitter API key. You need to first apply for an API key on Twitter's Developer site. It may take a while for them to get back to you.

When the app is created, note down your API key and API key secret. Then, in the Developer Portal, select your project from the sidebar and go to the "Keys and tokens tab". Here you can generate an "Access Token & Secret" which you will also need.

ParameterDefaultDescription
TWITTER_CONSUMER_KEY--The API key from the Twitter Developer Portal
TWITTER_CONSUMER_SECRET--The API key secret from the Twitter Developer Portal
TWITTER_ACCESS_TOKEN--The access token you generated in the steps above
TWITTER_ACCESS_TOKEN_SECRET--The access token secret you generated in the steps above

Once you've added these environment variables and restarted Plausible, you should see the relevant tweets the next day -- they are only fetched once every 24 hours. For more information on the Twitter integration, see Twitter referrals.