Illustration showing the Plausible web analytics service dashboard and logo

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.

Installing Plausible

Make sure you’ve got Git, Docker and Docker Compose installed. Begin by cloning down the plausible/hosting repository:

git clone
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.

image showing how to change the port used by Plausible in its docker-compose.yml

Next open 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.

image of Plausible's default configuration file

Replace the ADMIN_USER_EMAIL, ADMIN_USER_NAME and 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.

image of Plausible bootstrap logs

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

Plausible login screen image

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.

Plausible dashboard image when no sites added

Return to 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

A single Plausible server can collect data from multiple independent websites. You must use the Plausible dashboard to register each site you’ll be monitoring. You then add the Plausible JavaScript tracking script to your site’s HTML. This reports each page view to your Plausible server. The minified tracking script weighs in at under 1KB.

image of adding a website to Plausible analytics

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, without any subdomain prefix. This lets metrics from both and be collected by the same site property. Choose an appropriate timezone to use when computing reports.

image of Plausible tracking code display

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>

        <meta charset="utf-8" />
        <title>My Website</title>
        <script async defer data-domain="" src="http://localhost:8000/js/plausible.js"></script>

        <h1>Example Website</h1>

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:

Register as your site domain in Plausible, then visit 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.

Exploring Plausible

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.

image of Plausible site dashboard

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.

image of Plausible site settings

The “Goals” section provides a basic goal tracking/event monitoring mechanism. You can define target URIs, such as /checkout-complete, which Plausible will track.

image of adding a goal to Plausible

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. localhost)
  • 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)
  • SMTP_HOST_SSL_ENABLED – Either true or false to 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:

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_ACCOUNT_ID and GEOIPUPDATE_LICENSE_KEY variables in your geoip/geoip.conf file.

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.

Profile Photo for James Walker James Walker
James Walker is a contributor to How-To Geek DevOps. He is the founder of Heron Web, a UK-based digital agency providing bespoke software development services to SMEs. He has experience managing complete end-to-end web development workflows, using technologies including Linux, GitLab, Docker, and Kubernetes.
Read Full Bio »