How To Install Umami Analytics on Rocky Linux 9

In the world of website analytics, privacy-focused solutions have gained significant traction as website owners seek alternatives to conventional tracking tools. Umami Analytics stands out as a lightweight, open-source option that respects user privacy while providing valuable insights into website performance. This comprehensive guide walks you through installing Umami Analytics on Rocky Linux 9, offering detailed instructions to help you set up this powerful analytics tool.

Introduction to Umami Analytics

Umami Analytics represents a paradigm shift in the way website traffic is tracked and analyzed. Unlike traditional analytics platforms like Google Analytics, Umami prioritizes user privacy without compromising on functionality. This lightweight, open-source solution provides website owners with comprehensive insights while respecting visitor privacy preferences.

One of the standout features of Umami is that it doesn’t use cookies to track visitors, eliminating the need for annoying cookie consent banners on your website. This makes it fully compliant with privacy regulations like GDPR, CCPA, and PECR right out of the box. The data collected remains completely under your control since you’re hosting it on your own server.

Umami presents analytics data through an intuitive, clean dashboard that displays essential metrics without overwhelming users with unnecessary information. You can track multiple websites from a single installation, making it perfect for agencies or organizations managing several web properties.

For Rocky Linux 9 users specifically, Umami offers seamless integration with the system’s robust architecture, providing a stable and secure analytics solution. Its minimal resource requirements make it ideal even for servers with modest specifications, ensuring your analytics platform won’t slow down your system.

Prerequisites and System Preparation

Before diving into the Umami installation process, ensuring your Rocky Linux 9 system meets all requirements will save you time and prevent potential issues. Let’s prepare your environment for a smooth installation experience.

Hardware and System Requirements

To run Umami Analytics effectively, your Rocky Linux 9 server should meet these minimum specifications:

• CPU: 1 core (2+ cores recommended for production)
• RAM: 1GB (2GB or more recommended)
• Storage: 10GB available disk space
• A fully qualified domain name (FQDN) pointing to your server (e.g., umami.yourdomain.com)

User Setup and System Updates

First, ensure you’re working with a user that has sudo privileges. If you’re not already logged in as such a user, create one:

sudo adduser umami_admin
sudo usermod -aG wheel umami_admin

Next, update your Rocky Linux 9 system to ensure all packages are current:

sudo dnf update -y
sudo dnf upgrade -y

Install essential packages that will be required throughout the installation process:

sudo dnf install -y wget curl nano unzip tar

Properly preparing your system establishes a solid foundation for the Umami installation. These preliminary steps help prevent compatibility issues and ensure security patches are applied before deployment.

Configuring the Firewall

Rocky Linux 9 uses firewalld as its default firewall management solution. Properly configuring your firewall is essential to allow necessary connections to your Umami installation while maintaining security.

Checking Firewall Status

First, check if firewalld is active on your system:

sudo systemctl status firewalld

If it’s not running, enable and start it:

sudo systemctl enable --now firewalld

Opening Required Ports

For your Umami installation, you’ll need to open certain ports to allow traffic:

# Allow SSH (if not already allowed)
sudo firewall-cmd --permanent --add-service=ssh

# Allow HTTP and HTTPS
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https

# Reload firewall to apply changes
sudo firewall-cmd --reload

Verify that the ports have been correctly opened by checking the firewall configuration:

sudo firewall-cmd --list-all

You should see ssh, http, and https listed under the services section. This configuration ensures that your server can receive secure SSH connections for administration and web traffic for accessing your Umami dashboard.

Installing Git

Git is essential for downloading Umami’s source code from its repository. Let’s install and configure Git on your Rocky Linux 9 system.

Installation Process

Install Git using the DNF package manager:

sudo dnf install -y git

After installation, verify that Git was installed correctly by checking its version:

git --version

You should see output indicating the installed Git version (e.g., “git version 2.39.2”).

Initial Git Configuration

Configure your Git identity with your name and email address. This information will be associated with any changes you make to the repository:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

This basic Git setup will allow you to clone the Umami repository and manage the codebase effectively. Git’s version control capabilities will also be valuable if you need to update or modify your Umami installation in the future.

Setting Up Node.js Environment

Umami is built on Node.js, so setting up the proper Node.js environment is crucial for a successful installation. Rocky Linux 9 may not include the required Node.js version in its default repositories, so we’ll use the NodeSource repository.

Adding the NodeSource Repository

Umami requires Node.js version 18.x or newer. Let’s add the NodeSource repository to get the correct version:

curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -

Installing Node.js and npm

Now install Node.js and npm (Node Package Manager):

sudo dnf install -y nodejs

Verify the installation by checking the Node.js and npm versions:

node --version
npm --version

You should see output confirming Node.js version 18.x and the corresponding npm version.

Installing Yarn Package Manager

Umami recommends using Yarn instead of npm for dependency management. Install Yarn using npm:

sudo npm install -g yarn

Verify the Yarn installation:

yarn --version

This Node.js environment provides the runtime and package management tools needed to run Umami effectively. The specific version requirements ensure compatibility with all of Umami’s features and dependencies.

Database Installation and Configuration

Umami supports both MariaDB (MySQL) and PostgreSQL databases. In this guide, we’ll cover both options so you can choose the one that best fits your needs.

Option 1: MariaDB Setup

MariaDB is a community-developed fork of MySQL that offers good performance and compatibility.

Installation

Install MariaDB server:

sudo dnf install -y mariadb-server

Start and enable the MariaDB service:

sudo systemctl enable --now mariadb

Secure your MariaDB installation:

sudo mysql_secure_installation

During this process, you’ll be prompted to:

• Set a root password
• Remove anonymous users
• Disallow root login remotely
• Remove test database
• Reload privilege tables

Creating the Database and User

Log in to the MariaDB shell:

sudo mysql -u root -p

Create a database and user for Umami:

CREATE DATABASE umami;
CREATE USER 'umamiuser'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON umami.* TO 'umamiuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Remember to replace ‘your_secure_password’ with a strong, unique password.

Option 2: PostgreSQL Setup

PostgreSQL is known for its reliability, feature robustness, and performance.

Installation

Install PostgreSQL:

sudo dnf install -y postgresql-server postgresql-contrib

Initialize the database:

sudo postgresql-setup --initdb

Start and enable the PostgreSQL service:

sudo systemctl enable --now postgresql

Creating the Database and User

Switch to the PostgreSQL user:

sudo -i -u postgres

Create a new database and user:

createdb umami
createuser umamiuser

Access the PostgreSQL shell to set the password and grant privileges:

psql

In the PostgreSQL shell:

ALTER USER umamiuser WITH ENCRYPTED PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE umami TO umamiuser;
\q
exit

Whether you choose MariaDB or PostgreSQL, the database will serve as the storage backend for all your analytics data, making proper setup and security crucial for your Umami installation.

Downloading and Preparing Umami

Now it’s time to download the Umami source code and prepare it for installation on your Rocky Linux 9 system.

Cloning the Repository

Create a directory for Umami and clone the repository:

mkdir -p /var/www
cd /var/www
sudo git clone https://github.com/umami-software/umami.git
cd umami

Setting Up the Project Directory

Ensure proper permissions for the Umami directory:

sudo chown -R $USER:$USER /var/www/umami

Install the dependencies using Yarn:

yarn install

This process may take several minutes as Yarn downloads and installs all required packages. The dependencies are essential for building and running the Umami application.

Understanding Directory Structure

After installation, familiarize yourself with Umami’s directory structure:

• /components: UI components
• /lib: Core functionality
• /pages: Website pages
• /public: Static assets
• /prisma: Database schema and migration files

Having the source code properly installed and dependencies satisfied prepares your system for configuring and running Umami. This clean installation ensures you’re working with the official, unmodified code from the Umami developers.

Configuring Umami Environment

Proper environment configuration is crucial for Umami to connect to your database and function correctly. Let’s set up the environment variables.

Creating the .env File

Create a .env file in the Umami directory:

cd /var/www/umami
nano .env

Add the following configuration, adjusting for your chosen database:

For MariaDB:

DATABASE_URL=mysql://umamiuser:your_secure_password@localhost:3306/umami
HASH_SALT=any-random-string
APP_SECRET=another-random-string
DISABLE_TELEMETRY=1
TRACKER_SCRIPT_NAME=custom

For PostgreSQL:

DATABASE_URL=postgresql://umamiuser:your_secure_password@localhost:5432/umami
HASH_SALT=any-random-string
APP_SECRET=another-random-string
DISABLE_TELEMETRY=1
TRACKER_SCRIPT_NAME=custom

Generating Secure Keys

For APP_SECRET and HASH_SALT, generate secure random strings:

openssl rand -base64 32

Use the output to replace “any-random-string” and “another-random-string” in your .env file.

Additional Configuration Options

Umami offers several additional configuration options:

• DISABLE_TELEMETRY=1: Prevents Umami from sending anonymous usage data
• TRACKER_SCRIPT_NAME=custom: Customizes the tracker script name to help avoid ad blockers
• COLLECT_RUNTIME_STATS=true: Enables collection of runtime statistics

These environment variables control how Umami connects to your database and how certain features operate. The correct configuration ensures data is stored properly and the application runs smoothly.

Building and Deploying Umami

With all dependencies installed and the environment configured, you’re ready to build and deploy Umami on your Rocky Linux 9 server.

Building the Application

Build the Umami application using Yarn:

cd /var/www/umami
yarn build

This process compiles the source code into optimized production files. It may take several minutes depending on your server’s performance.

Setting Up PM2 Process Manager

PM2 is a process manager for Node.js applications that helps keep your application running continuously. Install PM2 globally:

sudo npm install -g pm2

Start Umami using PM2:

pm2 start yarn --name "umami" -- start

Configure PM2 to automatically start Umami on system boot:

pm2 save
pm2 startup

Execute the command that PM2 provides to create the startup script.

Monitoring and Managing the Application

Check the status of your Umami application:

pm2 status

View logs to monitor for any issues:

pm2 logs umami

PM2 provides powerful tools for managing your Node.js application, ensuring it stays online and automatically restarts after system reboots or if the process crashes. This robust deployment setup gives you a reliable analytics platform that requires minimal maintenance.

Setting Up Nginx as a Reverse Proxy

Nginx will serve as a reverse proxy to forward requests to your Umami application, providing additional security and performance benefits.

Installing Nginx

Install Nginx on Rocky Linux 9:

sudo dnf install -y nginx

Start and enable the Nginx service:

sudo systemctl enable --now nginx

Configuring Nginx for Umami

Create a new Nginx configuration file for Umami:

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

Add the following configuration:

server {
    listen 80;
    listen [::]:80;
    server_name umami.yourdomain.com;
    
    access_log /var/log/nginx/umami.access.log;
    error_log /var/log/nginx/umami.error.log;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Replace umami.yourdomain.com with your actual domain name.

Testing and Applying the Configuration

Check the Nginx configuration for syntax errors:

sudo nginx -t

If there are no errors, reload Nginx to apply the changes:

sudo systemctl reload nginx

This reverse proxy setup creates a more secure and flexible deployment by handling client connections while forwarding requests to the Umami application running on port 3000. It also allows for easy implementation of SSL/TLS encryption in the next section.

Securing the Installation with SSL/TLS

Adding SSL/TLS encryption is essential for securing your Umami installation. Let’s use Certbot to obtain free Let’s Encrypt certificates.

Installing Certbot

Install Certbot and its Nginx plugin:

sudo dnf install -y epel-release
sudo dnf install -y certbot python3-certbot-nginx

Obtaining SSL Certificates

Request certificates for your domain:

sudo certbot --nginx -d umami.yourdomain.com

Follow the prompts to:

• Enter your email address
• Agree to the terms of service
• Choose whether to redirect HTTP traffic to HTTPS (recommended)

Certbot will automatically update your Nginx configuration to use the new certificates.

Setting Up Auto-Renewal

Let’s Encrypt certificates are valid for 90 days. Test the renewal process:

sudo certbot renew --dry-run

Certbot installs a systemd timer that will attempt to renew certificates when they’re close to expiration, but it’s good to verify this is working correctly.

Verifying Secure Access

Open your browser and visit https://umami.yourdomain.com. You should see a secure connection indicator (lock icon) in your browser’s address bar.

Implementing SSL/TLS encryption protects data transmitted between users and your Umami installation, including login credentials and analytics data. This security measure is especially important for administrative interfaces and data collection endpoints.

Initial Umami Setup and Configuration

After installation, you need to complete the initial setup to begin using Umami for your websites.

First Login

Access your Umami installation through your web browser at https://umami.yourdomain.com.

For a fresh installation, use the default credentials:

• Username: admin
• Password: umami

You’ll be prompted to change the default password immediately after your first login.

Creating Your Admin Account

After logging in with the default credentials:

1. Navigate to the Settings page
2. Create a new administrator account with a strong password
3. Log out and log back in using your new account
4. Delete or disable the default admin account for security

Configuring System Settings

In the Settings section, configure:

• Your preferred timezone for accurate reporting
• Default date range for reports
• Language preferences
• Theme options (light/dark mode)

These initial configuration steps secure your Umami installation and personalize it according to your preferences. Taking the time to set up proper administrator accounts and configure system settings ensures your analytics platform is ready for production use.

Adding Websites and Implementing Tracking

Now that Umami is set up and secured, you can start tracking your websites.

Adding a Website to Umami

1. Log in to your Umami dashboard
2. Navigate to the Settings page
3. Click on “Add website”
4. Enter the website details:
   • Name: A descriptive name for your site
   • Domain: Your website’s domain (e.g., example.com)
   • Enable share URL: Optional, allows sharing analytics publicly
5. Click “Save” to create the website

Retrieving and Implementing the Tracking Code

After adding your website:

1. Click on the website in your dashboard
2. Select the “Settings” tab
3. Copy the provided tracking code
4. Add this script to the <head> section of your website

For WordPress sites, you can use a plugin or add the code to your theme’s header.php file. For static sites, simply include the script in all HTML pages.

Custom Script Name for Ad Blocker Bypass

Since you configured TRACKER_SCRIPT_NAME=custom in your environment settings, Umami uses a non-standard script name that may help bypass ad blockers. You can further enhance this by serving the script from your own domain using Nginx.

Create a new location block in your Nginx configuration:

location = /js/script.js {
    proxy_pass https://umami.yourdomain.com/custom.js;
    proxy_set_header Host $host;
    proxy_buffering on;
    expires 1h;
}

This configuration serves the tracking script from a custom path, making it less likely to be blocked by ad blockers.

Understanding Analytics Dashboard

Umami’s dashboard provides comprehensive analytics data in an easy-to-understand format.

Key Metrics Overview

The main dashboard displays:

• Pageviews: Total number of page loads
• Unique visitors: Distinct users who visited your site
• Bounce rate: Percentage of visitors who navigate away after viewing only one page
• Average visit time: How long visitors typically stay on your site

Real-time Visitor Monitoring

The real-time view shows:

• Current active visitors on your site
• Pages they’re viewing
• Referral sources
• Geographic locations
• Device and browser information

Data Visualization and Reporting

Umami presents data through various charts and graphs:

• Line charts showing traffic trends over time
• Bar graphs comparing metrics across different periods
• Pie charts illustrating visitor demographics
• Tables listing top pages and referral sources

Understanding these analytics helps you make informed decisions about your website’s content and marketing strategies. The visual presentation makes complex data accessible and actionable, even for users without technical expertise in analytics.

Advanced Customization

Umami offers several advanced customization options to tailor the analytics platform to your specific needs.

Custom Event Tracking

Beyond page views, you can track specific user interactions:

umami.trackEvent('button_click', {
  button_name: 'subscribe',
  user_type: 'new_visitor'
});

This code tracks when users click a specific button, along with additional context about the interaction.

User Roles and Permissions

For organizations with multiple team members, create additional user accounts with appropriate permissions:

• Administrators: Full access to all features and settings
• Viewers: Can only view analytics for specific websites

Manage these roles through the Settings page in your Umami dashboard.

Data Retention Policies

Customize how long Umami retains your analytics data by modifying your database configuration. This is particularly useful for compliance with privacy regulations that may require limiting data retention periods.

These advanced features allow you to get more detailed insights from your analytics while maintaining control over data access and storage. Custom tracking events, in particular, can provide valuable information about how users interact with specific elements of your website.

Maintenance and Updates

Regular maintenance ensures your Umami installation remains secure and performs optimally.

Updating Umami

To update Umami to the latest version:

cd /var/www/umami
git pull
yarn install
yarn build
pm2 restart umami

Check the Umami GitHub repository regularly for new releases and update notes.

Database Maintenance

Periodic database maintenance improves performance:

For MariaDB:

sudo mysql -u root -p -e "OPTIMIZE TABLE umami.*;"

For PostgreSQL:

sudo -u postgres psql -d umami -c "VACUUM ANALYZE;"

Backup Procedures

Implement regular backups of your Umami database:

For MariaDB:

mysqldump -u root -p umami > umami_backup_$(date +%Y%m%d).sql

For PostgreSQL:

pg_dump -U postgres umami > umami_backup_$(date +%Y%m%d).sql

Store these backups securely, preferably off-server, to protect against data loss.

Proper maintenance ensures your analytics platform remains reliable and your valuable visitor data stays protected. Regular updates also provide access to new features and security patches as they become available.

Troubleshooting Common Issues

Even with careful installation, you might encounter issues. Here are solutions to common problems.

Database Connection Errors

If Umami can’t connect to your database:

1. Verify database service is running: sudo systemctl status mariadb or sudo systemctl status postgresql
2. Check credentials in your .env file
3. Ensure the database user has proper permissions
4. Try connecting to the database manually to verify access

Nginx Configuration Problems

If your Umami site isn’t accessible:

1. Check Nginx error logs: sudo tail /var/log/nginx/error.log
2. Verify syntax: sudo nginx -t
3. Ensure Nginx is running: sudo systemctl status nginx
4. Confirm firewall settings allow HTTP/HTTPS traffic

Tracking Script Not Recording Data

If analytics aren’t being recorded:

1. Check browser console for JavaScript errors
2. Verify the tracking script is correctly implemented
3. Check if ad blockers are preventing script execution
4. Ensure your site’s domain matches what’s configured in Umami

PM2 Process Management Issues

If Umami stops running:

1. Check PM2 status: pm2 status
2. View logs for errors: pm2 logs umami
3. Restart the process: pm2 restart umami
4. Ensure PM2 startup script is configured correctly: pm2 save and pm2 startup

Most issues can be resolved by carefully checking configuration files, reviewing log files, and ensuring all services are running correctly. The Umami community forums and GitHub issues are also valuable resources for troubleshooting specific problems.

Congratulations! You have successfully installed Umami Analytics. Thanks for using this tutorial for installing the Umami modern analytics platform on Rocky Linux 9 system. For additional help or useful information, we recommend you check the official Umami website.