How to Run Plausible Analytics in a Docker Container

If you’re looking for a self-hosted, privacy-friendly alternative to Google Analytics, then learning how to run Plausible Analytics in a Docker Container is an excellent alternative.

In this article, we have divided the entire process into sections featuring detailed steps for each, as it is lengthy and complex. 

To walk you through setting up Plausible Analytics in a Docker Container, we have considered Ubuntu 22.04.2 LTS as the platform.

Let’s begin.

What You Will Need

Before we proceed with the setup, it is necessary to go through the below prerequisites to prevent errors:

1. Domain Name: If you don’t already have a domain name, it is necessary to purchase one to use with Plausible Analytics. Namecheap is a reputable, trusted domain registrar that you can consider for this purpose.
   
2. SSL Certificate for Domain Name: Generate an SSL certificate for your domain to enable secure communication over HTTPS. If you’re using Namecheap, here’s the guide on how to generate an SSL certificate for your purchased domain name.
   
3. VPS Plan: Create a virtual private server (VPS) to deploy the Plausible Analytics container and ensure it is compatible with Docker and Plausible Analytics. DigitalOcean offers an affordable option with their $4 per month DigitalOcean Droplet (VPS) instance, which can conveniently do this. 

Without any of the above, learning how to run Plausible Analytics in a Docker container would not be possible. If you have gathered everything, we can proceed with the setup process.

How to Run Plausible Analytics in a Docker Container: Step-by-Step

Step 1: Install Docker CE on Ubuntu Linux

1. Start by retrieving information about available software updates from the configured repositories using the command below:

sudo apt update

2. Now upgrade your installed packages to their latest versions using the command below:

sudo apt upgrade

3. Once you’re done updating and upgrading the system, type the code below to install packages to allow apt to use a repository over HTTPS:

sudo apt -y install lsb-release gnupg apt-transport-https ca-certificates curl software-properties-common

4. Now enter the Docker’s GPG (GNU Privacy Guard) key, which will be used to verify the authenticity and integrity of Docker images:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/docker.gpg

5. Next, it’s time to install Docker CE. Here is the command to add the stable build repository:

sudo add-apt-repository "deb [arch=$(dpkg --print-architecture)] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

6. Once the GPG key and the stable repository are added, it is ideal to update the system again before installing the Docker CE to prevent errors:

sudo apt update

7. After successfully performing Steps 1-6, you’re ready to install Docker CE. Type the below command to start the installation:

sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin

8. It is recommended to use Docker as a non-root user instead of relying on the root user every time. Follow the commands below to add a new user:

sudo usermod -aG docker $USER
newgrp docker

Take note that executing the above commands will not generate any output. Hence you can proceed with the subsequent steps assuredly.

9. Execute the following command to verify if Docker CE has been successfully installed. If you receive no response or encounter an error, then it is recommended to repeat all the steps:

docker version 

Once done with the steps, type docker compose version to check if Docker Compose is installed. If no output is generated for the command, then we will proceed to the next step to install Docker Compose before you can start working on how to run Plausible Analytics in a Docker container. 

Step 2: Install Docker Compose on Linux   

1. After you have installed Docker CE, update the configured repositories using the command below;

sudo apt update

2. After updating the system, access the terminal with sudo privileges to install the “curl and wget” packages using the below commands.

sudo apt install -y curl wget 

3. Once you have installed curl, download the latest Docker Compose on your Linux machine using the curl command below:

curl -s https://api.github.com/repos/docker/compose/releases/latest | grep browser_download_url  | grep docker-compose-linux-x86_64 | cut -d '"' -f 4 | wget -qi –

4. After downloading the compose file, make the binary file executable using the below command:

chmod +x docker-compose-linux-x86_64

The command doesn’t generate any output. However, you can see in the screenshot below that the access privileges have been updated for the binary file:

5. Now move the file to the path featuring all Docker files using the below command:

sudo mv docker-compose-linux-x86_64 /usr/local/bin/docker-compose

This command doesn’t generate any output either. Nonetheless, you can see in the screenshot below that the file is listed in the specific path:

6. To confirm if Docker Compose has been installed, enter the following command. If there is no response, or an error occurs, it is advisable to repeat all the steps.:

docker-compose version

Before proceeding with the configuration of Plausible Analytics, update the system and install “git” and “vim.”  Installing these components is mandatory, as “git” facilitates image-related functionalities, while “vim” enables easy editing of config files.

The command below updates the system and helps install Git and Vim:

sudo apt update && sudo apt install git vim

Step 3: Configure Plausible Analytics Container

1. To start the container, the first and foremost thing to do is clone the hosting repo. There are various methods to accomplish this, but the simplest and most efficient approach is using git. Here is the command to clone the repository:

git clone https://github.com/plausible/hosting plausible

2. Once you have successfully cloned the repo into the “plausible” directory, change the current directory to the newly created directory by using the command below:

cd plausible

After changing the directory to “plausible,” we need to generate a random hash string to adjust the “plausible-conf.env” as it contains variables for the container. 

Use the following code to generate the random hash string:

openssl rand 64 | base64 -w 0 ; echo

After executing the command, the generated random hash string will be displayed. Copy this string and paste it into the text editor of your choice (we will be using Notepad) for future reference when managing the configuration files.

3. Once you have generated the random hash string, edit the “plausible-conf.env” through the Vim editor using the below command:

vim plausible-conf.env

Fill in the details for each variable by pressing the ‘I’ key, and paste the generated random hash string as the input to the “SECRET_KEY_BASE” variable.

Once done with the changes, press the Escape (Esc) key and type ‘:wq’ to save and exit Vim.

4. After you have successfully configured the “plausible-conf.env” file, make modifications to the “docker-compose.yml” file using the below command:

vim docker-compose.yml

Note: As we modify the YML file, any white spaces, improper syntax or structure can throw errors. Hence, ensure that you’re typing the commands exactly as suggested.

Copy and paste the text from the following GitHub repo hosting/docker-compose.yml into the “docker-compose.yml” file.

The yml file contains the same variables in the “plausible-conf.env” file at the bottom. Ensure that both config files have the same values, and if the “docker-compose.yml” doesn’t feature the ‘environment’ section, add the below lines at the end of the image.

Once done with the changes, press the Escape (Esc) key and type ‘:wq’ to save and exit Vim. However, before exiting Vim, copy the commands entered and paste them into YAML Lint to identify if it’s valid and gain a clean UTF-8 version. With the installation done, you can now understand how to run Plausible Analytics in a Docker container.

Step 4: How to Run Plausible Analytics in a Docker Container 

1. After modifying both files, you can start the containers using the below command:

docker compose up -d

2. Now verify the state of the containers using the below command. This step helps identify any potential issues with the containers.  If any issues are found, you will need to edit the “docker-compose.yml” file accordingly.

docker ps

3. Once you have reviewed the configuration and confirmed that the containers are running smoothly, you can proceed to verify if the homepage is accessible. You can use either of the following commands to check the accessibility:

curl http://localhost:8000 
curl http://serverip:8000

Step 5: Configure Nginx Reverse Proxy

Nginx is widely recognized as a reverse proxy that improves performance through compression, caching offloading, and efficient handling of static files. 

By leveraging these capabilities, Nginx optimizes the serving process, improving performance and overall efficiency.  

1. Before proceeding further, update the system and ensure that Nginx is installed on your system.

The command below updates the systemsand install Nginx:

sudo apt update && sudo apt install nginx -y

2. After successfully installing Nginx, allow HTTP and HTTPS through the firewall using the below command:

sudo ufw allow "Nginx Full"

3. After updating the rules, the next step is to create a new virtual host file. A virtual host file is a configuration file used by Nginx to define the settings and behavior for a specific website or domain hosted on the server.
   
   To create the virtual host file, execute the following command:

sudo vim /etc/nginx/conf.d/plausible.conf

For the variable named ‘server_name’, provide your server/domain name as the input. Save the file by typing ‘:wq‘ inside Vim and restart the service.

4. Once you’re done with Steps 1-3, enable Nginx using the below command:

sudo systemctl enable --now nginx

Step 6: Configure SSL for Plausible Analytics

You can proceed with configuring SSL for Plausible Analytics if you have generated certificates for your domain name. However, if you don’t have the certificates and have a fully qualified domain name, you can easily obtain certificates using Let’s Encrypt.

1. Create a new config file named “plausible_ssl.conf” – Fill in the details, and replace your IP Address wherever needed.

vim plausible_ssl.conf

2. Now generate a new 2048-bit RSA private key and save it to the file ‘plausible_ssl.key’ using the below command:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout plausible_ssl.key -out plausible_ssl.crt -config plausible_ssl.conf

3. After successfully generating the certs, copy the generated certs to the /etc/ssl/certs using the below commands:

sudo cp plausible_ssl.crt /etc/ssl/certs/plausible_ssl.crt
sudo mkdir -p /etc/ssl/private/
sudo cp plausible_ssl.key /etc/ssl/private/plausible_ssl.key

4. Once you have successfully performed Steps 1-3, adjust the config file using the below command and modify the HTTPS port using the lines in the image in the server block.

sudo vim /etc/nginx/conf.d/plausible.conf

The above config file for the Nginx server block is used to listen on port 443 (HTTPS) and set up SSL/TLS using the specified SSL certificate and key files. 

Additionally, it defines the server name, log file paths, and a proxy configuration to pass requests to a local web server running on ‘localhost:8000’.

5. After making changes to the configuration, the last thing to do is restart the Nginx service using the restart command:

sudo systemctl restart nginx

Step 7: Access Plausible Analytics Web Interface

Once you have successfully configured SSL for Plausible Analytics, you are done with installing and configuration part, and you’re left with accessing the Plausible web interface. It is now time to understand how to run Plausible Analytics in a Docker container and configure it.

1. To access the Plausible web interface, enter the URL – https://domain_name/ (replace the domain_name with yours) in a standard web browser.

2. Fill in the details or register, and once you’re authenticated, you need to enter the domain or subdomain along with the reporting time zone.

3. Plausible generates a Javascript snippet that needs to be added to your site’s HTML code to sync the website with Plausible. 

Once done, clear the cache of your domain and click on the ‘Start collecting data‘ button. This step helps collect the metrics and waits for page visits to the set website.

4. After Plausible has collected the data successfully, you have successfully finished the setup of how to run Plausible Analytics in a Docker container. Here’s what the output should look like (screenshot below):

That brings us to the end of this post. We have broken down the entire process and explained the process with detailed steps. Additionally, we have discussed possible errors and provided their diagnosis. 

The reason behind learning how to run Plausible Analytics in a Docker container is that it is simpler to manage dependencies, guarantee consistency across environments, and make easy deployments.

Considering Plausible Analytics and its scaling, portability, and isolation, it is an excellent choice for businesses and developers. 

If this guide helped you, please share it.