Plausible is an open-source alternative to Google Analytics. It’s available as a commercial hosted product and as free self-hosted software. In this guide, we’ll show you how to setup Plausible and start gaining insights into your website’s traffic.
Plausible focuses on privacy, simplicity and actionable metrics. It’s compliant with GDPR, CCPA and PECR legislation. Plausible doesn’t set cookies on your visitors’ devices, so you won’t need intrusive privacy banners on your homepage.
The Plausible web dashboard has a minimal design that lets you see visitor counts, total page views, bounce rates and visit durations. There’s also overview data on origin countries, referring sources and visitor device types.
To self-host Plausible, you’ll need Docker and Docker Compose. Plausible is available on Docker Hub as
plausible/analytics but additional containers are required to run the database servers. It’s recommended you use the official Docker Compose file in the
plausible/hosting GitHub repository to get started.
Make sure you’ve got Git, Docker and Docker Compose installed. Begin by cloning down the
git clone https://github.com/plausible/hosting cd hosting
The repository contains pre-prepared configuration files that let you quickly spin up a fresh Plausible installation. The
docker-compose.yml file should be ready to use. It links the dependency containers to the main Plausible app container.
Plausible will be exposed on port 8000 on your host. If you’d prefer a different port, such as
8800, find the
ports: line in the
plausible section of
docker-compose.yml. Change the next line from
- 8000:8000 to
- 8800:8000 to bind host port 8800 to the container’s port 8000.
plausible-conf.env in your editor. This is the configuration file for the Plausible application server. It includes five default settings. They define the server’s domain and setup an initial administrator user.
ADMIN_USER_PWD values with your email address, name and password respectively. Your password must be at least six characters long. Set
BASE_URL to the domain your Plausible server will be hosted on. You can use
http://localhost:8000 for local testing.
The final configuration tweak is to provide a secret key to protect Plausible’s authentication system. Generate a random string and add it as the value of
SECRET_KEY_BASE. The string must be 64 characters long. You can use
openssl rand to create a secure value:
openssl rand -base64 64
Now you’re ready to start Plausible!
docker-compose up -d
It may take several seconds for Docker to pull the container images and start all the services. Once the pull process is complete, run
docker logs hosting_plausible_1 --follow to check whether bootstrap is complete.
http://localhost:8000 in your browser when you see “migrations successful” appear in the logs. You should see the Plausible login screen. Login with the email address and password you configured.
You’ll be prompted to activate your account. The activation process sends you a verification code via email. The default configuration doesn’t include functioning outgoing email, so it’s best to manually skip this stage.
Run the following command in your terminal:
docker exec hosting_plausible_db_1 psql -U postgres -d plausible_db -c "UPDATE users SET email_verified = true;"
This runs a plain SQL query against the Plausible database. The query will clear the pending verification flag from every user.
http://localhost:8000 in your browser. You should now see the Plausible dashboard. It will be empty as you haven’t added any sites.
Connecting Your Website to Plausible
Click “Add a website” in the Plausible dashboard. You’ll need to supply some basic information about your site. Enter the domain name root as
example.com, without any subdomain prefix. This lets metrics from both
www.example.com be collected by the same site property. Choose an appropriate timezone to use when computing reports.
Click the “Add snippet” button to confirm your settings. Plausible will display your site’s
<script> tag snippet. Add the code to the
<head> section of your website’s HTML. Each page load will download the script and report metrics back to Plausible.
<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <title>My Website</title> <script async defer data-domain="example.com" src="http://localhost:8000/js/plausible.js"></script> </head> <body> <h1>Example Website</h1> </body> </html>
Plausible doesn’t work with
localhost domains. If you want to test against a site running on your machine, consider using
/etc/hosts to map a temporary domain to it:
foobar.net as your site domain in Plausible, then visit
foobar.net in your browser. Your website should display and hits will start appearing in Plausible.
Once you’ve finished setting up your site connection, click Plausible’s “Start collecting data” button to visit your site’s dashboard.
Plausible’s simplistic UI gives you a quick at-a-glance overview of your site’s performance. Key metrics such as total page views and unique visitors are shown at the top of the screen. Further down your dashboard, you’ll see lists of your top-performing pages, external referrers and visitor device types. Data defaults to showing the last 30 days; you can change this using the dropdown in the top-right.
To access your site settings, click the site name in the top-left. Press “Site settings” in the dropdown menu. Here you can manage your site’s configuration.
The “Visibility” section lets you make your dashboard publicly visible, without logging into Plausible. You can also generate unique sharable links which you can distribute to specific people.
The “Goals” section provides a basic goal tracking/event monitoring mechanism. You can define target URIs, such as
/checkout-complete, which Plausible will track.
Create goals by heading to the “Goals” section, clicking “Add goal” and filling out the form to provide a page URI to track. When a user visits the URI, it’ll show up under “Goal Conversions” at the bottom of your dashboard.
Setting Up Email
The “Email reports” site settings item lets you opt-in to weekly site performance reports and unusual traffic spike notifications. These won’t work unless you provide Plausible with proper outgoing email settings.
Plausible can send via an SMTP server or the Postmark transactional email service. To use SMTP, update your
plausible-conf.env with the following additional settings:
MAILER_EMAIL– Email address which Plausible will send as
SMTP_HOST_ADDR– SMTP server to connect to (e.g.
SMTP_HOST_PORT– SMTP server port
SMTP_USER_NAME– Username to connect as
SMTP_USER_PWD– Password to supply to the SMTP server (when needed)
falseto indicate whether to use SSL for SMTP connections.
If you want to use Postmark, first make sure you’ve got a Postmark account and API key. Then update
plausible-conf.env with the following settings:
MAILER_ADAPTER=Bamboo.PostmarkAdapter POSTMARK_API_KEY=your api key
Once you’re done tweaking your Plausible configuration, run
docker-compose up -d to apply the changes and restart your containers. You should now be able to use Plausible’s email functions.
Enabling Country Data
Plausible’s dashboard includes a map widget that shows the countries your visitors originate from. This data isn’t enabled by default. It has a dependency on the
database, which isn’t distributed with Plausible itself.
You need a GeoLite2 account to activate Plausible’s geolocation features. Creating an account will produce an account ID and license key. Substitute these values into the
GEOIPUPDATE_LICENSE_KEY variables in your
Next, use the following command to add a GeoLite2 database container to your Plausible stack:
docker-compose -f docker-compose.yml -f geoip/docker-compose.geoip.yml up
Docker will pull the GeoLite database and make it available to the Plausible container. Future page view events should then include geolocation data which will be visible on the Plausible dashboard.
Plausible is a simple website analytics system which you can self-host. It lets you inspect the reach of your site without relying on a third-party service. Users won’t be tracked across the web or frustrated by cookie banners.
You can update to future Plausible versions by running
git pull and
docker-compose up -d --pull. This will update your running server instance to match the latest Plausible image published to Docker Hub.