The ultimate guide to Umami Analytics

Umami Analytics, Ultimate guide.
Photo: Krivec Ales, Pexels.

Analytics are an essential part of almost every good website. These little surf aids don’t just tell you where surfers are on your site, but they also help you as webmaster to be able to improve your site as well. Umami is software for web analytics and is a privacy-friendly, alternative to Google Analytics.

The app can be installed for free on your own server of choice. Thus the data is and remains in your own control. It is GDPR (General Data Protection Regulation) compliant. I.e. a cookie consent solution (website cookie banner) is not necessary, for websites within the European Union.

Umami as Node.js app


We use CloudPanel in the example. CloudPanel is a free control panel that allows multiple apps or sites to run on the same server. Node.js and MariaDB can also be installed manually on your server. But that is beyond the scope of this how-to.

As a CloudPanel user. Navigate to Sites, Add Site. And create a New Node.js Site with domain https://analytics.yourdomain.com and forward traffic to App port: 3003. Where port 3003 is the port Umami is listening on. Node.js Version: Node 18 LTS. Note and memorize the Site User and User Password.

This is where we're going to log in to the terminal shortly. Add a new Database based on MariaDB from Databases. With Database Name, Database User Name and Database User Password in accordance with your wishes. Continue the installation from the installation paragraph.

Umami as Docker container

Umami is also available in the flavor: Docker. Albeit we prefer the non-Docker variant. Nevertheless. To access Umami via the domain https://analytics.yourdomain.com.

As CloudPanel user. Navigate to Sites, Add Site. Create a Reverse Proxy on domain https://analytics.yourdomain.com.

  • Forward traffic to http://127.0.0.1:3000 as Reverse Proxy Url.

Continue your journey at Dockerized Umami. 

Umami Installation

Umami is easy to setup. To setup Umami through the example domain https://umami.yourdomain.com:

  • Login to the terminal as the CloudPanel user you just agitated.
  • Install package manager yarn: npm install -g yarn
  • Clone the source into the project folder and change directory: git clone https://github.com/umami-software/umami.git ~/htdocs/umami.yourdomain.com
    cd ~/htdocs/umami.yourdomain.com
  • Create the configuration file: nano .env or a text editor of your own choosing. With specifications (for example) where your database is and your user:
    DATABASE_URL=mysql://yourdatabaseuser:yourpassword@127.0.0.1:3306/yourdatabasename
    DISABLE_UPDATES=1
    DISABLE_TELEMETRY=1
    PORT=3003
    IGNORE_IP =yourip

    We turn off updates. After all, there is no need to automatically search for updates every time (browser notifications). Updates cannot be installed through the browser anyway. Subscribe to the mailing list for updates, is our recommendation.

    So that you receive updates for each app which you use, at the same address. Well-managed in one place. In addition, we disable the telemetry. The reason speaks for itself. It is not desirable that analytics software, that markets itself as privacy focused. Does send unsolicited telemetric data on its own (opt-out).

    And finally we exclude the ip address of our webmasters. After all, you don't want false positives in your data.

  • Install the dependencies for the project: yarn install
  • Build the app: yarn build
  • Install the production process manager: pm2: npm install pm2 -g
  • Start the app for the first time: pm2 start yarn --name umami -- start -- --port=3003
  • Create startup file with the startup script generator: pm2 startup
  • Take a snapshot of your currently running Node application: pm2 save
  • Review the current path with: echo $PATH
    Set the start parameters into a cronjob: crontab -e or your cron manager of choice.
    For example: @reboot /home/umami.yourdomain.com/.nvm/versions/node/v18.16.0/bin/node /home/umami.yourdomain.com/.nvm/versions/node/v18.16.0/bin/pm2 resurrect
  • Optional but recommended. Exclude and disable Next.js framework telemetry in the terminal with: yarn next telemetry disable
    It amazes us how much telemetry just gets installed as an opt-out these days. Really, almost every software now sends everything through. In which it is not always clear exactly what. To supposedly "improve the user experience" is too easy as far as we are concerned. Opt-in should be the norm in our view.

Continue at the paragraph finalizing. 

Dockerized Umami

Login as root since Docker runs as root user by default. Umami uses multiple Docker containers, including the PostgreSQL database and the analytics software itself.

  • Install docker and the docker compose plugin:
    curl -sSL https://get.docker.com/ | CHANNEL=stable sh && apt install docker-compose-plugin
  • Create the directory and download the project files:
    mkdir /opt/umami-dockerized && git clone https://github.com/umami-software/umami.git /opt/umami-dockerized
  • You'll need a random 64-character secret key which will be used to secure the APP, also known as the: APP_SECRET.
    openssl rand -base64 64 | tr -d '\n' ; ech and write down the code.
  • Nano (or your favorite text edit) /opt/umami-dockerized/docker-compose.yml and add the APP_SECRET with the previously generated code.
  • Initialize Umami Docker by executing the docker compose command:
    cd /opt/umami-dockerized && docker compose up -d

Finalizing the installation (general)

Surf to https://umami.yourdomain.com and login for the first time with the default user; User: admin, Password "umami". Without ",": Change the default password and optionally the default username for safety considerations. Add the website to track your audience. Add the java tracking snippet to the website and start collecting data.

You could add the production SSL certificate. On the SSL/TLS tab of the CloudPanel, choose: New Let's Encrypt Certificate section. Your own Umami server is ready to go. A user-friendly and privacy-friendly. With the latest General Data Protection Regulation and affiliated legislation in mind (GDPR).

Keeping your Umami system up-to-date

This chapter describes the process of keeping your Umami system up-to-date. Which involves the way feature, security -updates are installed and applying changes introduced by the newly updated packages. 

  • Back-up the current app.
  • Login to the terminal as the CloudPanel user you just agitated.
  • Navigate to the project folder: cd ~/htdocs/umami.yourdomain.com
  • Update the app source: git pull
  • Install new dependencies (if available) for the project: yarn install
  • (Re)Build the app: yarn build

And for the Docker edition:

  • Backup the current containers.
  • Login into the terminal as the root user.
  • Download the latest files and start the new containers: cd /opt/umami-dockerized && docker compose pull && docker compose up --force-recreate

Should you be looking for something just a little different. Plausible is an alternative that also focuses on privacy-friendly analytics. It is a Docker based only product, though.

Related posts