This section is for self-hosting our analytics on your server and managing your infrastructure (installation, maintenance, upgrades, server capacity, uptime, backup and so on). This is different from Plausible Analytics Cloud where we manage everything for your ease and convenience. Take a look at the differences between Plausible Cloud and Self-Hosted.
When running a Plausible release, the following configuration parameters can be supplied as environment variables.
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.
|ADMIN_USER_NAME||autogenerated||Admin user's name|
|ADMIN_USER_EMAIL||autogenerated||The default ("admin") user email|
|ADMIN_USER_PWD||autogenerated||The default ("admin") user password.|
Following are the variables that can be used to configure the availability of the server.
|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.|
|SECRET_KEY_BASE||--||An internal secret key used by Phoenix Framework. Follow the instructions to generate one.|
|DISABLE_AUTH||false||Disables authentication completely, no registration, login will be shown.|
|DISABLE_REGISTRATION||false||Disables registration of new users, keep your admin credentials handy ;)|
|DATABASE_URL||postgres://localhost:5432/plausible_dev||The database URL as dictated here, i.e. for external db server postgres://user:firstname.lastname@example.org/database_name|
|DATABASE_SOCKET_DIR||--||Directory where a UNIX socket of postgresql is available. Mutually exclusive with |
|DATABASE_NAME||--||Name of the database in PostgreSQL to use. Only applicable in conjunction with |
|CLICKHOUSE_DATABASE_URL||http://localhost:8123/plausible_dev||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.|
Plausible uses a SMTP server to send transactional emails e.g. account activation, password reset, weekly reports, etc.
|MAILER_EMAILemail@example.com||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:
|MAILER_ADAPTER||Bamboo.SMTPAdapter||Instead of the default, replace this with |
|POSTMARK_API_KEY||--||Enter your API key.|
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 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:
|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
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
- Visit the Google API Console to obtain OAuth 2.0 credentials such as a Client ID and Client Secret key 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 get your Client ID and Client Secret key.
Go to your Plausible installation's public URL followed by
/auth/google/callbackas "Authorized redirect URI".
Copy the Client ID and Client Secret key from your project in Google API Console into these config values:
|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" on your Google API project.
- 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.
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.
|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.
Self-hosting our analytics product is free as in beer. You only need to pay for your server and whatever cost there is associated with running a server. You never have to pay any fees to us, only to your cloud server provider. If you choose to self-host Plausible you can become a sponsor which is a great way to give back to the community and to contribute to the long-term sustainability of the project. Simply put, we treat sponsors like paying customers which means you can receive guaranteed priority support.