How To Install Umami Analytics on Fedora 41

In this tutorial, we will show you how to install Umami Analytics on Fedora 41. Umami Analytics has emerged as a powerful alternative to conventional web analytics platforms, offering a privacy-focused approach that respects user data while providing comprehensive insights. Unlike traditional analytics tools that rely on cookies and collect personal information, Umami operates without cookies and fully complies with GDPR regulations, making it an excellent choice for privacy-conscious website owners. This comprehensive guide walks you through the complete process of installing Umami Analytics on Fedora 41, from preparation to final configuration.

Understanding Umami Analytics

What Makes Umami Different

Umami stands apart from conventional analytics tools through its privacy-first approach. The platform doesn’t use cookies, doesn’t collect personal data, and gives you complete ownership of your analytics information. This respect for privacy doesn’t come at the expense of functionality—Umami provides powerful insights without compromising user data.

Website owners increasingly seek analytics solutions that align with modern privacy expectations and regulations. Umami meets these needs by focusing on anonymous, aggregate data rather than individual tracking. The data stays on your server, giving you full control over how it’s stored and used.

Core Features Overview

Umami offers an impressive feature set despite its privacy-focused design:

• Real-time data tracking capabilities that show visitor activity as it happens
• Customizable dashboards that can be tailored to highlight metrics most relevant to your needs
• Event tracking functionality for measuring specific user interactions like button clicks
• Multi-site support for managing analytics across multiple websites from a single installation
• Simple website integration with a lightweight JavaScript snippet

The platform presents data through an intuitive interface with clean visualizations, making it easy to extract actionable insights without a steep learning curve.

Use Cases for Umami

Umami proves valuable across various scenarios:

• Personal websites and blogs seeking basic traffic insights without surveillance
• Business websites concerned with privacy regulations and user trust
• Projects requiring GDPR compliance and transparent data practices
• Organizations looking for ethical alternatives to conventional analytics
• Self-hosted enthusiasts who prefer keeping control of their data

Prerequisites

System Requirements

Before proceeding with installation, ensure your Fedora 41 system meets these requirements:

• Minimum: 1GB RAM, 2 CPU cores, 20GB storage
• Recommended: 2GB RAM, 2+ CPU cores, 40GB storage for optimal performance

While Umami can run on modest hardware, allocating additional resources will improve responsiveness, especially for websites with higher traffic volumes.

Required Software and Skills

The installation process requires:

• Basic command line proficiency
• A domain name pointed to your server’s IP address
• SSH access to your Fedora 41 server
• Root or sudo privileges

Familiarity with web servers and databases is helpful but not mandatory, as this guide covers all required steps in detail.

Pre-Installation Checklist

Complete these preparations before proceeding:

• Fully update your Fedora 41 system with the latest packages
• Configure firewall rules to allow necessary traffic (ports 80, 443, and 3000)
• Ensure your server has a stable internet connection
• Allocate approximately 30-60 minutes for the complete installation process

Installation Methods Overview

Umami offers multiple installation approaches to accommodate different preferences and technical requirements:

• Source Code Installation (primary focus) provides the most control over your installation and enables customization options not available through containerized deployments.
• Docker-Based Installation (alternative approach) simplifies the process by encapsulating Umami and its dependencies in a standardized container, reducing complexity and potential conflicts.
• Docker Compose Setup (for multi-container deployments) offers orchestration capabilities that streamline management of complex setups with multiple components.

Each method achieves the same result—a functioning Umami instance—but the best choice depends on your specific requirements and technical comfort level.

Method 1: Installing Umami from Source

Preparing Your Fedora 41 System

Begin by updating your system to ensure you have the latest security patches and package updates:

sudo dnf update -y

Install essential development packages and dependencies:

sudo dnf install -y git curl wget nano

Configure your firewall to allow necessary traffic:

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --reload

Verify the firewall configuration:

sudo firewall-cmd --list-all

Installing Node.js and Yarn

Umami requires Node.js version 14 or newer for optimal performance. Install Node.js:

sudo dnf module reset nodejs
sudo dnf module enable nodejs:18
sudo dnf install -y nodejs

Verify the Node.js installation:

node --version

Next, install Yarn package manager, which Umami uses for dependency management:

sudo npm install -g yarn

Verify the installation:

yarn --version

Database Setup

Umami supports both PostgreSQL and MySQL/MariaDB databases. This guide uses PostgreSQL for its robust performance. Install PostgreSQL:

sudo dnf install -y postgresql postgresql-server
sudo postgresql-setup --initdb
sudo systemctl enable postgresql
sudo systemctl start postgresql

Create a database user and the Umami database:

sudo -i -u postgres
createuser -P umami
# Enter a secure password when prompted
createdb -O umami umami
exit

Configure PostgreSQL for secure access by editing the authentication configuration:

sudo nano /var/lib/pgsql/data/pg_hba.conf

Locate the line for local connections and change ident to md5:

# TYPE  DATABASE        USER            ADDRESS                 METHOD
local   all             all                                     md5

Save the file and restart PostgreSQL:

sudo systemctl restart postgresql

Test the database connection:

psql -h localhost -U umami -d umami
# Enter the password you created
# Type \q to exit

Downloading and Building Umami

Clone the Umami repository from GitHub:

git clone https://github.com/umami-software/umami.git
cd umami

Install the required dependencies:

yarn install

Create and configure the environment file:

cp .env.example .env
nano .env

Configure the database connection string in the .env file:

DATABASE_URL=postgresql://umami:yourpassword@localhost:5432/umami

Replace yourpassword with the database password you created earlier.

Build the application:

yarn build

The build process creates the initial admin account with username admin and password umami.

Start the application to verify everything is working:

yarn start

Visit http://your-server-ip:3000 in your browser to confirm Umami is running. You should see the login page.

Method 2: Docker Installation

Setting Up Docker on Fedora 41

Install Docker and Docker Compose:

sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

Start and enable the Docker service:

sudo systemctl enable docker
sudo systemctl start docker

Add your user to the Docker group (optional, for running Docker without sudo):

sudo usermod -aG docker $USER
# Log out and back in for this to take effect

Test the Docker installation:

docker --version
docker compose version

Deploying Umami with Docker

Create a project directory:

mkdir ~/umami-docker && cd ~/umami-docker

Create a docker-compose.yml file:

nano docker-compose.yml

Add the following configuration:

version: '3'
services:
  umami:
    image: docker.umami.is/umami-software/umami:postgresql-latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:umami@db:5432/umami
      DATABASE_TYPE: postgresql
      HASH_SALT: your-random-string
    depends_on:
      - db
    restart: always
  db:
    image: postgres:14-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: umami
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    restart: always

volumes:
  umami-db-data:

Replace your-random-string with a unique random string for security.

Start the containers:

docker compose up -d

Check the container status:

docker compose ps

Access Umami at http://your-server-ip:3000 and log in with the default credentials (username: admin, password: umami).

Web Server Configuration

Nginx Setup as Reverse Proxy

Install Nginx:

sudo dnf install -y nginx

Create a new server block configuration:

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

Add the following configuration:

server {
    listen 80;
    server_name your-domain.com;

    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 your-domain.com with your actual domain name.

Test the Nginx configuration:

sudo nginx -t

If the test passes, enable and restart Nginx:

sudo systemctl enable nginx
sudo systemctl restart nginx

SSL Certificate Implementation

Install Certbot for Let’s Encrypt SSL certificates:

sudo dnf install -y certbot python3-certbot-nginx

Obtain an SSL certificate:

sudo certbot --nginx -d your-domain.com

Follow the prompts to complete the certificate installation. Certbot automatically modifies your Nginx configuration to enable HTTPS.

Test your secure connection by visiting https://your-domain.com.

Configure automatic certificate renewal:

sudo systemctl enable certbot-renew.timer
sudo systemctl start certbot-renew.timer

This ensures your SSL certificates are automatically renewed before expiration.

Post-Installation Setup

First-time Login

Access your Umami installation at https://your-domain.com and log in with the default credentials:

• Username: admin
• Password: umami

Immediately change the default password:

1. Click on your username in the top-right corner
2. Select “Settings”
3. Click “Change password”
4. Enter a strong, unique password
5. Click “Save”

Systemd Service Configuration

For source-code installations, create a systemd service to manage Umami:

sudo nano /etc/systemd/system/umami.service

Add the following configuration:

[Unit]
Description=Umami Analytics
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/umami
ExecStart=/usr/bin/yarn start
Restart=on-failure
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Replace your-username with your system username and /path/to/umami with the actual path to your Umami installation.

Enable and start the service:

sudo systemctl enable umami
sudo systemctl start umami

Monitor the service status:

sudo systemctl status umami

This ensures Umami runs continuously and restarts automatically after system reboots.

Implementing Tracking on Websites

Generating Tracking Code

Log in to your Umami dashboard and add a website:

1. Navigate to “Settings” > “Websites”
2. Click “Add website”
3. Enter your website details:
   • Name: A descriptive name for your site
   • Domain: Your website’s domain (without http/https)
   • Enable share URL: Optional, creates a public dashboard link
4. Click “Save”

After adding your website, Umami generates a tracking code snippet. Click “Details” next to your website entry to view the code.

Implementation Methods

For WordPress Sites

Install a plugin like “Header and Footer Scripts” or “Insert Headers and Footers,” then add the Umami tracking script to the site header.

For Static HTML Sites

Add the tracking code to the <head> section of your HTML:

<script async defer data-website-id="your-website-id" src="https://your-domain.com/umami.js"></script>

Replace your-website-id with the ID provided in your Umami dashboard and your-domain.com with your actual domain.

For Other CMS Platforms

Most content management systems provide options to add custom scripts to the site header. Consult your CMS documentation for specific instructions.

Verifying Tracking Works

After implementing the tracking code:

1. Visit your website in a browser
2. Return to your Umami dashboard
3. Check the “Realtime” section to confirm visitor activity
4. Perform various actions on your site to verify event tracking

If no data appears, try clearing your browser cache and refreshing the page.

Troubleshooting Common Issues

Database Connection Problems

If Umami cannot connect to the database:

• Verify the database credentials in your .env file
• Ensure PostgreSQL is running: sudo systemctl status postgresql
• Check database logs: sudo journalctl -u postgresql
• Test direct database connection: psql -h localhost -U umami -d umami
• Confirm firewall rules allow database connections

Common error: “Could not connect to database” typically indicates incorrect credentials or PostgreSQL configuration issues.

Node.js and Build Issues

If the build process fails:

• Ensure Node.js version is 14 or newer: node --version
• Clear the Yarn cache: yarn cache clean
• Remove the node_modules directory and reinstall: rm -rf node_modules && yarn install
• Check for disk space issues: df -h
• Review build logs for specific error messages

Networking and Firewall Problems

If you cannot access Umami after installation:

• Verify the application is running: sudo systemctl status umami or docker compose ps
• Check firewall rules: sudo firewall-cmd --list-all
• Ensure SELinux isn’t blocking connections: sudo setenforce 0 temporarily disables SELinux for testing
• Verify Nginx configuration: sudo nginx -t
• Check Nginx logs: sudo tail -f /var/log/nginx/error.log

Web Server Configuration Issues

For Nginx-related problems:

• Ensure server blocks are correctly configured
• Verify domain DNS resolves to your server
• Check for syntax errors in configuration files
• Restart Nginx after configuration changes: sudo systemctl restart nginx
• Review logs for specific errors: sudo journalctl -u nginx

Maintenance and Updates

Keeping Umami Updated

For source code installations:

cd /path/to/umami
git pull
yarn install
yarn build
sudo systemctl restart umami

For Docker installations:

cd ~/umami-docker
docker compose pull
docker compose down
docker compose up -d

Regular updates ensure you have the latest features and security patches.

Database Maintenance

Implement a backup strategy:

# Create a database backup
pg_dump -U umami umami > umami_backup_$(date +%Y%m%d).sql

# Automate backups with a cron job
crontab -e
# Add: 0 2 * * * pg_dump -U umami umami > /path/to/backups/umami_backup_$(date +%Y%m%d).sql

Periodically clean old data to maintain performance:

-- Connect to the database
psql -U umami umami

-- Delete data older than 6 months
DELETE FROM session WHERE created_at < NOW() - INTERVAL '6 months';
DELETE FROM pageview WHERE created_at < NOW() - INTERVAL '6 months';
DELETE FROM event WHERE created_at < NOW() - INTERVAL '6 months';

Security Best Practices

• Change default credentials immediately after installation
• Implement strong, unique passwords for all accounts
• Keep all system packages updated: sudo dnf update -y
• Configure automatic security updates: sudo dnf install dnf-automatic
• Regularly review access logs for suspicious activity
• Restrict SSH access to specific IP addresses when possible

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