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.