Configuration options
The easiest way to get started with Plausible is with our official managed service in the Cloud. It takes 2 minutes to start counting your stats with a worldwide CDN, high availability, backups, security and maintenance all done for you by us. Our managed hosting can save a substantial amount of developer time and resources. For most sites this ends up being the best value option and the revenue goes to funding the maintenance and further development of Plausible. So you’ll be supporting open source software and getting a great service! The section below is for self-hosting our analytics on your server and managing your infrastructure.
When running a Plausible release, the following configuration parameters can be supplied as environment variables.
Server
Following are the variables that can be used to configure the availability of the server.
| Parameter | Default | Description |
|---|---|---|
| BASE_URL | -- | The hosting URL of the server, used for URL generation. In production systems, this should be your ingress host. |
| PORT | 8000 | The port on which the server is available. |
| LISTEN_IP | 0.0.0.0 | The IP address on which the server is listening. 0.0.0.0 means all interfaces, 127.0.0.1 means localhost. Also see the related section Erlang platform ports below. |
| SECRET_KEY_BASE | -- | An internal secret key used by Phoenix Framework. Follow the instructions or use openssl rand -hex 64 to generate one. |
| DISABLE_REGISTRATION | false | Restricts registration of new users. Possible values are true (full restriction), false (no restriction), and invite_only (only the invited users can register). |
Erlang platform ports
When changing the LISTEN_IP of the Plausible HTTP server, you may also wish to change the listen IPs of the Erlang VM and Port Mapper Daemon (epmd) normally started by Plausible. They allow remote code execution and are listening on all interfaces by default. You can change that by setting the environment variables:
RELEASE_VM_ARGS, to e.g.-kernel inet_dist_use_interface "{127,0,0,1}"ERL_EPMD_ADDRESSto e.g.127.0.0.1
Alternatively, if you are running on a single machine and don't need any of Erlang's multi-node distribution features, you turn them off entirely by setting environment variable:
RELEASE_DISTRIBUTIONtonone
Database
Plausible uses PostgreSQL for storing user data and ClickhouseDB for analytics data. Use the following variables to configure it.
| Parameter | Default | Description |
|---|---|---|
| DATABASE_URL | postgres://localhost:5432/plausible_db | The database URL as dictated here, i.e. for external db server postgres://user:password@ip.or.domain.to.server/database_name |
| DATABASE_SOCKET_DIR | -- | Directory where a UNIX socket of postgresql is available. Mutually exclusive with DATABASE_URL, can only be used with DATABASE_NAME |
| DATABASE_NAME | -- | Name of the database in PostgreSQL to use. Only applicable in conjunction with DATABASE_SOCKET_DIR |
| ECTO_IPV6 | -- | When defined, enables ipv6 for the PostgreSQL connection. Applicable for hosting on fly.io. |
| CLICKHOUSE_DATABASE_URL | http://localhost:8123/plausible_events_db | Connection string for Clickhouse in the same format, i.e. for docker-compose setup http://plausible_events_db:8123/plausible_events_db |
| CLICKHOUSE_FLUSH_INTERVAL_MS | 5000 | Interval (in milliseconds) between flushing events and sessions data to Clickhouse. Consult Clickhouse docs before changing it. |
| CLICKHOUSE_MAX_BUFFER_SIZE | 10000 | Maximum size of the buffer of events or sessions. Consult Clickhouse docs before changing it. |
Mailer/SMTP Setup
Plausible uses a SMTP server to send transactional emails e.g. account activation, password reset. In addition, it sends non-transactional emails like weekly or monthly reports.
| Parameter | Default | Description |
|---|---|---|
| MAILER_EMAIL | hello@plausible.local | The email id to use for as from address of all communications from Plausible. |
| SMTP_HOST_ADDR | localhost | The host address of your smtp server. |
| SMTP_HOST_PORT | 25 | The 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_ENABLED | false | If SSL is enabled for SMTP connection |
| SMTP_RETRIES | 2 | Number of retries to make until mailer gives up. |
Alternatively, you can use Postmark to send transactional emails. In this case, use the following parameters:
| Parameter | Default | Description |
|---|---|---|
| MAILER_ADAPTER | Bamboo.SMTPAdapter | Instead of the default, replace this with Bamboo.PostmarkAdapter |
| POSTMARK_API_KEY | -- | Enter your API key. |
In case you are using postmark, you have to set the MAILER_EMAIL variable which needs to be configured in PostmarkApps sender signatures.
IP Geolocation
Plausible uses the country database created by dbip for enriching analytics data with visitor countries. The database is shipped with Plausible and country data collection happens automatically.
Optionally, you can provide a different database. For example, you can use MaxMind services. 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:
| Parameter | Default | Description |
|---|---|---|
| GEOLITE2_COUNTRY_DB | -- (internal database) | 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.
Google API Integration
To enable the Google Search Console integration and Google Analytics imports, you first need to authorize your self-hosted installation with a Google Account. Complete the following two tasks to do so.
Task One: Configure the OAuth Consent Screen
- Login to Google API Console with your Google Account. Once on the API Console, create a new project for the Plausible integration.
Make sure your new Project is open, select "OAuth consent screen" from the left side menu to configure the consent screen. If you can't see the "OAuth consent screen" menu item, open the navigation ("hamburger") menu in the top left corner and select "APIs & Services". "OAuth consent screen" is a menu item below that.
Enter an "App name" and a "User support email". Again, to help with naming, remember that the "app" is your self-hosted Plausible site which will be requesting access to the Search Console API using your Google Account, so you are probably the only user.
Apart from the mandatory "Developer contact information" fields, the only other necessary setting is the "Authorized domains" which must include the domain used for the earlier "Authorized Redirect URIs" setting. That is, add the domain (eg.
example.com) of your Plausible installation's public URL. All subdomains will be authorized automatically.Click "SAVE AND CONTINUE". No "Scopes" are required, so click "SAVE AND CONTINUE" again.
The "app" will be created with status set to "Testing". To avoid having to verify it with Google, you must enter the email address of your Google Account as a "Test user". Add the email address and then click "SAVE AND CONTINUE" and the OAuth Consent Screen configuration is complete.
Task Two: Create an OAuth Client
- We will need to obtain OAuth 2.0 credentials such as a Client ID and Client Secret key that are known to both Google and your installation. Make sure your new Project is open, then go to the "Credentials" screen and get your Client ID and Client Secret key. If you can't see the "Credentials" menu item, open the navigation ("hamburger") menu in the top left corner and select "APIs & Services". "Credentials" is a menu item below that.
Use the "+ CREATE CREDENTIALS" button near the top of the screen to create a new "OAuth client ID". Set the "Application type" to "Web application" and give it a name. To help with naming, note that your self-hosted Plausible site will be the "client" that is accessing an API exposed by your Google account.
Use the "+ ADD URI" button to set an "Authorized redirect URI" to your Plausible installation's public URL followed by
/auth/google/callback. Eg.https://plausible.example.com/auth/google/callback. Then click "CREATE".
- Copy the Client ID and Client Secret key from your project in Google API Console into these config values (that is, add them to
plausible-conf.env):
| Parameter | Default | Description |
|---|---|---|
| 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 |
- Force the new config values to take effect by restarting your Plausible site (eg. with the command
docker-compose down --remove-orphans && docker-compose up -d).
Google Search Integration
Although you can now grant your Plausible installation access to your Google account, you still won't be able to choose a property from the Search Console as described in Google Search Console Integration, until you enable the "Google Search Console API" on your Google API project.
Enable Google Search Console API
- Click on "Enable APIs and Services."
- Search for "Google Search Console API" in the search bar of the API Library.
- Click on "Google Search Console API" and the button to enable.
Finally, return to APIs & Services, and select "Domain verification". If you can't see the "Domain verification" menu item, open the navigation ("hamburger") menu in the top left corner and select "APIs & Services". "Domain verification" is a menu item below that.
Add the same domain you used in Step 2 above. You will be prompted to go to Google Search Console to finish configuration, which coincidentally is exactly where you need to be to start the Google Search Console Integration instructions.
Google Analytics Integration
To be able to import data from Google Analytics, you need to enable Analytics Reporting API and Google Analytics API.
Once those services are enabled, follow the instructions outlined in Import stats from Google Analytics. Note that when going through Google Auth, you need to make sure the "See and download your Google Analytics data." checkbox is selected.
Our only source of funding is our premium, managed service for running Plausible in the cloud. If you're looking for an alternative way to support the project, we've put together some sponsorship packages. Maintaining open source software is a thankless, time-consuming job. We released our code on GitHub and made it easy to self-host on principle, not because it's good business. If you're self-hosting Plausible, sponsoring us is a great way to give back to the community and to contribute to the long-term sustainability of the project. Thank you for supporting independent creators of Free Open Source Software!