This quick‑start guide walks you through installing the open‑source analytics platform Umami on a fresh CentOS 8 host, covering everything from updating the system to configuring environment variables. It begins by adding required packages such as git, curl, and Node.js from NodeSource, then shows how to create a dedicated low‑privilege user to run Umami safely. Next you’ll set up MariaDB or MySQL, build the application with npm, and adjust the .env file so the app knows where its database lives and what base URL to expose. Finally, the tutorial explains how to launch the app manually, optionally wrap it in a systemd service for persistence, and optionally add an Nginx reverse proxy to secure access and forward traffic to port 3000.

Installing Umami on CentOS 8 – A Quick, No‑Nonsense Guide

If you’re running a fresh CentOS 8 host and want to get the open‑source analytics platform Umami up and running, this is the recipe. I’ll walk through what you need, why each step matters, and where the common hiccups pop up.

1 – Install Prerequisites

sudo dnf update -y
sudo dnf install -y git curl wget nano

Why it matters: CentOS ships with a very lean stack. Git pulls the source; curl or wget fetches the installer scripts; nano gives you an editor that works in any terminal.

On CentOS 8, Node.js 14 isn’t available by default, so we’ll add the NodeSource repo:

curl -fsSL https://rpm.nodesource.com/setup_14.x | sudo bash -
sudo dnf install -y nodejs

If you prefer using nvm, just run the installer script and then nvm install 14. Either way, Umami needs a Node.js runtime that supports ES modules.

2 – Create a Dedicated User

Umami should never run as root. Make a low‑privilege account:

sudo useradd -m -s /bin/bash umami
sudo passwd umami

Why it matters: A separate user keeps your analytics data isolated and prevents accidental system modifications if the app is compromised.

3 – Pull the Repository

Switch to the new user, clone Umami, then enter the folder:

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

If you see a warning about an unsupported init.d script, ignore it – we’ll use Docker instead.

4 – Install and Configure the Database

Umami works best with MariaDB (or MySQL). On CentOS 8, MariaDB is in AppStream:

sudo dnf install -y mariadb-server
sudo systemctl enable --now mariadb

Secure the installation:

sudo mysql_secure_installation

Create a database and user:

CREATE DATABASE umami CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON umami.* TO 'umamiuser'@'localhost' IDENTIFIED BY 'StrongPassword123!';
FLUSH PRIVILEGES;
EXIT;

Real‑world note: I’ve seen this error after a bad driver update that left MySQL hanging on InnoDB: Unable to lock file .... Running mysqlcheck --repair --all-databases usually clears it up.

5 – Build Umami

Umami is built with npm, so you’ll need the package manager installed earlier:

npm install

If the build stalls on a missing header file, try installing the development tools:

sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y python3-devel

6 – Configure Environment Variables

Copy the sample config and edit it:

cp .env.example .env
nano .env

Set these to match your database:

DATABASE_URL=mysql://umamiuser:StrongPassword123!@localhost/umami?ssl=false
BASE_URL=http://your.server.ip
APP_HOST=0.0.0.0
APP_PORT=3000
APP_SECRET=SomeRandomSecretString

Why it matters: DATABASE_URL tells Umami where to find its data; BASE_URL is what your visitors see, and the secret protects against CSRF.

7 – Start the App

npm run start

Open a browser to http://your.server.ip:3000. The first launch will prompt you to create an admin account. After that, you can log in and see real‑time metrics.

If the service crashes with “Error: Cannot find module ‘dotenv’”, double‑check that you ran npm install as the umami user and that you’re inside the project directory when launching.

8 – (Optional) Run as a Service

For production, wrap Umami in systemd:

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

Add:

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

[Service]
Type=simple
User=umami
WorkingDirectory=/home/umami/umami
EnvironmentFile=/home/umami/umami/.env
ExecStart=/usr/bin/npm run start
Restart=always

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl enable --now umami.service

Now it restarts automatically if the host reboots or the node process dies.

9 – Secure with Nginx (Optional)

If you’re behind a reverse proxy, install nginx and point it to port 3000. A minimal config:

sudo dnf install -y httpd
sudo nano /etc/httpd/conf.d/umami.conf

Insert:

<VirtualHost *:80>
    ServerName analytics.example.com

    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:3000/
    ProxyPassReverse / http://127.0.0.1:3000/

    ErrorLog logs/umami-error_log
    CustomLog logs/umami-access_log common
</VirtualHost>

Restart:

sudo systemctl enable --now httpd

That’s it! Your CentOS 8 server should now be humming with fresh visitor data.

Enjoy your analytics journey, and feel free to ping me if you hit any snags. Happy tracking!