Umami Analytics: Install and Configure on Debian 12 Easily

Umami Analytics is a lightweight, open-source, self-hosted web analytics solution that provides a privacy-focused alternative to Google Analytics and other paid analytic tools. It offers the advantage of not placing any cookies on the user’s browser, eliminating the need for annoying cookie banners on your website. In this tutorial, we will guide you through the process of installing Umami Analytics on a Debian 12 server, allowing you to track and analyze website statistics.

Prerequisites

Before we begin with the installation process, make sure you have the following prerequisites in place:

A server running Debian 12.
A non-root user with sudo privileges.
A fully qualified domain name (FQDN) pointing to your server, such as umami.example.com.

Additionally, ensure that the Uncomplicated Firewall (UFW) is enabled and running on your server. To update your system and install essential packages, run the following commands:

$ sudo apt update && sudo apt upgrade
$ sudo apt install wget curl nano ufw software-properties-common dirmngr apt-transport-https gnupg2 ca-certificates lsb-release debian-archive-keyring unzip -y

Step 1 – Configure Firewall

The first step is to configure the firewall on your Debian 12 server. By default, Debian comes with UFW (Uncomplicated Firewall). Check if the firewall is running by executing the following command:

$ sudo ufw status

If the firewall is inactive, enable it using the following commands:

$ sudo ufw allow OpenSSH
$ sudo ufw allow http
$ sudo ufw allow https
$ sudo ufw enable

Make sure to allow SSH, HTTP, and HTTPS ports to ensure uninterrupted access to your server. After enabling the firewall, check its status again:

$ sudo ufw status

The output should display that the firewall is active and running.

Step 2 – Install Git

Git is required to clone Umami’s official repository. Install Git by running the following command:

$ sudo apt install git

Verify the installation by checking the Git version:

$ git --version

Step 3 – Install Node

Umami is a JavaScript app that runs on Node.js. To install Node.js, we will use Nodesource’s installer. Since Node.js version 16.0 is the current stable version, we will install that. Execute the following commands to install Node.js:

$ curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/nodesource.gpg
$ NODE_MAJOR=18
$ echo "deb [signed-by=/usr/share/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list
$ sudo apt update
$ sudo apt install nodejs

To verify the Node.js installation, run the following command:

$ node --version

Step 4 – Install MariaDB Server

Debian 12 does not ship with MySQL by default, and an official package for it has not been released yet. Therefore, we will be using MariaDB as an alternative. Debian 12 ships with MariaDB 10.11.4, so we will install that. Execute the following command to install MariaDB:

$ sudo apt install mariadb-server

Check the installed version of MariaDB:

$ mysql --version

Step 5 – Download Umami

Before downloading Umami, we need to install the Yarn package manager. Install Yarn using NPM:

$ sudo npm install -g yarn

Once Yarn is installed, clone Umami’s GitHub repository:

$ git clone https://github.com/mikecao/umami.git

Switch to the newly created directory:

$ cd umami

Install the necessary Umami modules:

$ yarn install

Step 6 – Configure Umami

To configure Umami, we need to create MySQL credentials and populate the database. Enter the MySQL shell by running the following command:

$ sudo mysql

Create a new user and database for Umami:

mysql> CREATE USER 'umamiuser'@'localhost' IDENTIFIED BY 'YourPassword';
mysql> CREATE DATABASE umami;
mysql> GRANT ALL PRIVILEGES ON umami.* TO 'umamiuser'@'localhost';

Replace 'YourPassword' with a strong password of your choice. Next, flush the privileges and exit the MySQL shell:

mysql> FLUSHPRIVILEGES;
mysql> exit

After creating the MySQL credentials, we need to configure Umami’s environment variables. Generate a strong app secret using the OpenSSL command:

$ openssl rand30 | openssl base64-Abu4orqfdlG+Dh3Otau4oWSBbI9kGWSkGfYc/WiH/

Create a .env file to store the environment variables:

$ touch.env

Open the .env file for editing:

$ nano.env

Paste the following code into the .env file:

DATABASE_URL=mysql://umamiuser:YourPassword@localhost:3306/umami
APP_SECRET=bu4orqfdlG+Dh3Otau4oWSBbI9kGWSkGfYc/WiH/
DISABLE_TELEMETRY=1
TRACKER_SCRIPT_NAME=custom

Replace 'YourPassword' with the password you set for the umamiuser MySQL user. Save and close the file.

Step 7 – Running Umami

Now that everything is set up, build the Umami application:

$ yarn build

To run Umami in the background, we will use PM2 (Advanced Production Process Manager for Node.js). Install PM2 globally:

$ sudo yarn global add pm2

Start the Umami application:

$ pm2 start yarn --name umami -- start

Save the Umami application with PM2 for future use:

$ pm2 save

To ensure that Umami restarts automatically if it crashes or is killed, create a systemd script:

$ pm2 startup

Follow the instructions provided by the command output to generate the startup script.

Step 8 – Install Nginx

By default, Debian 12 ships with an older version of Nginx. To install the latest version, we need to download the official Nginx repository. Import Nginx’s signing key:

$ curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg > /dev/null

Add the repository for Nginx’s stable version:

$ echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] http://nginx.org/packages/debian `lsb_release -cs` nginx" | sudo tee /etc/apt/sources.list.d/nginx.list

Update the system repositories:

$ sudo apt update

Install Nginx:

$ sudo apt install nginx

Step 9 – Install SSL using Let’s Encrypt

To secure your Umami installation with SSL, we will use Let’s Encrypt to generate free SSL certificates. Install Certbot, which is used to obtain and renew SSL certificates:

$ sudo apt install snapd
$ sudo snap install core
$ sudo snap refresh core
$ sudo snap install --classic certbot
$ sudo ln -s /snap/bin/certbot /usr/bin/certbot

Verify the Certbot installation:

$ certbot --version

Generate the SSL certificate for your Umami domain:

$ sudo certbot certonly --nginx --agree-tos --no-eff-email --staple-ocsp --preferred-challenges http -m test@shapehost.com -d umami.example.com

Replace test@shapehost.com with your email address and umami.example.com with your FQDN.

Generate a Diffie-Hellman group certificate:

$ sudo openssl dhparam-dsaparam -out /etc/ssl/certs/dhparam.pem 4096

Check the Certbot renewal scheduler service:

$ sudo systemctl list-timers

Perform a dry run to test the SSL certificate renewal process:

$ sudo certbot renew --dry-run

If there are no errors, your SSL certificate will renew automatically.

Step 10 – Configure Nginx

Create and open the Nginx configuration file for Umami:

$ sudo nano /etc/nginx/conf.d/umami.conf

Paste the following code into the file:

server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name umami.example.com;
access_log /var/log/nginx/umami.access.log;
error_log /var/log/nginx/umami.error.log;

# SSL
ssl_certificate /etc/letsencrypt/live/umami.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/umami.example.com/privkey.pem;
ssl_trusted_certificate /etc/letsencrypt/live/umami.example.com/chain.pem;
ssl_session_timeout 5m;
ssl_session_cache shared:MozSSL:10m;
ssl_session_tickets off;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
ssl_ecdh_curve X25519:prime256v1:secp384r1:secp521r1;
ssl_stapling on;
ssl_stapling_verify on;
ssl_dhparam /etc/ssl/certs/dhparam.pem;
resolver 8.8.8.8;

location / {
proxy_pass http://localhost:3000;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}

# Enforce HTTPS
server {
listen 80;
listen [::]:80;
server_name umami.example.com;
return 301 https://$host$request_uri;
}

Replace umami.example.com with your FQDN. Save and close the file.

Open the Nginx configuration file for editing:

$ sudo nano /etc/nginx/nginx.conf

Add the following line before the include /etc/nginx/conf.d/*.conf; line:

server_names_hash_bucket_size64;

Save and close the file.

Verify the Nginx configuration file syntax:

$ sudo nginx -t

If there are no syntax errors, restart the Nginx service:

$ sudo systemctl restart nginx

Step 11 – Set up a Site and Collect Statistics

Access your Umami Analytics dashboard by visiting https://umami.example.com in your web browser. You will be prompted to log in using the default administrator account with the username admin and password umami.

Once logged in, you will be directed to the Umami Analytics dashboard. To start tracking statistics for your website, visit the settings page and click on “Add website.” Enter the necessary details and click “Save.”

To embed the Umami tracking code into your website, click on the “Edit” button for the corresponding website and switch to the “Tracking code” tab. Copy the provided code and paste it between the header or footer HTML tags of your website. Umami will start collecting data within a few minutes.

Step 12 – Update Umami

To update Umami to the latest version, navigate to the Umami installation directory:

$ cd ~/umami

Stop the Umami application:

$ pm2 stop umami

Install any new or updated dependencies:

$ yarn install

Rebuild the Umami application:

$ yarn build

Start the Umami application:

$ pm2 start umami

Congratulations! You have successfully installed and configured Umami Analytics on your Debian 12 server. You can now track and analyze website statistics using this lightweight and privacy-focused solution.

Conclusion

In this tutorial, we have covered the step-by-step process of installing Umami Analytics on a Debian 12 server. By following these instructions, you can set up a self-hosted web analytics solution that provides valuable insights into your website’s performance without compromising user privacy. Umami Analytics is a lightweight and open-source alternative to paid analytic tools, offering features such as cookie-free tracking and customizable tracking code. With Umami, you can make data-driven decisions and optimize your website’s performance effectively.

Remember, if you need reliable and scalable cloud hosting solutions, Shape.host provides Cloud VPS services that can meet your business needs. Shape.host offers efficient, secure, and cost-effective hosting options, allowing you to focus on growing your business while leaving the technical aspects to the experts. Visit Shape.host today to explore their range of cloud hosting solutions tailored to your specific requirements.