One place for hosting & domains


      How To Install Umami Web Analytics Software on Ubuntu 20.04


      Umami is an open-source, self-hosted web analytics application written in Node.js. It focuses on being simple, well-designed, fast, and privacy-focused. It can store data about your website’s visitors in either a MySQL or PostgreSQL database.

      In this tutorial you will install Umami and a PostgreSQL database using Docker Compose, then install Nginx to act as a reverse proxy for Umami. Finally, you will enable secure HTTPS connections by using Certbot to download and configure SSL certificates from the Let’s Encrypt Certificate Authority.


      In order to complete this tutorial, you’ll first need the following:

      Note: These prerequisite steps can be skipped if you’re using DigitalOcean’s 1-Click Docker Image. This image will have Docker, Docker Compose, and UFW already installed and configured.

      Launch a new Docker image in the region of your choice, then log in as the root user and proceed with the tutorial. Optionally, you could leave off the sudo parts of all commands, but it’s not necessary.

      Finally, to enable SSL you’ll need a domain name pointed at your server’s public IP address. This should be something like or, for instance. If you’re using DigitalOcean, please see our DNS Quickstart for information on creating domain resources in our control panel.

      When you’ve satisfied all the prerequisites, proceed to Step 1, where you’ll download and launch the Umami software.

      Step 1 — Installing Umami and PostgreSQL with Docker Compose

      Your first step will be to clone the Umami Git repository, update the docker-compose.yml configuration file, and then start the Umami and PostgreSQL containers.

      You’ll download the repo into the /opt directory. Use the cd command to go there now:

      Then use the git command to clone the repo from GitHub:

      • sudo git clone

      This will pull all the software and configuration files into /opt/umami. Move into the newly created umami directory now:

      Now you need to update the project’s docker-compose.yml file. This file is what the docker-compose command uses to configure and launch multiple Docker containers at once. We need to change two options in this file: the IP that Umami binds to, and a random hash used as a salt when encrypting things in the database.

      Before you open docker-compose.yml to edit it, let’s generate a new random hash to paste into the file:



      This uses the openssl command to generate 32 random characters. Copy the output to your clipboard, then open the configuration file:

      • sudo nano docker-compose.yml

      Find the HASH_SALT option, delete the placeholder text, and paste in the random hash you just generated:


      . . .
            HASH_SALT: replace-me-with-a-random-string
      . . .

      Next, find the ports: portion of the configuration:


      . . .
            - ""
      . . .

      Update the "3000:3000" value by prepending to it. This ensures that Umami is only listening on the localhost interface, and is not publicly available. Even though you have a UFW firewall set up, due to some quirks in how Docker networking works, if you didn’t take this step your Umami container would be accessible to the public on port 3000.

      With those configuration changes complete, save the file (CTRL+O then ENTER in nano) and close out of your editor (CTRL+X).

      Now, use docker-compose to start up your two containers:

      • sudo docker-compose up --detach

      The --detach flag tells docker-compose to create the containers in the background, detached from our terminal session:


      . . . Creating umami_db_1 ... done Creating umami_umami_1 ... done

      Umami and PostgreSQL are now running. You can verify this by using the curl command to fetch the homepage of your new Umami container running on localhost:


      <!DOCTYPE html><html><head><meta charSet="utf-8"/> . . .

      If a large chunk of HTML is output to your terminal, you know the Umami server is up and running.

      Next, we’ll set up Nginx to reverse proxy Umami from localhost:3000 to the public.

      Step 2 — Installing and Configuring Nginx

      Putting a web server such as Nginx in front of your Node.js server can improve performance by offloading caching, compression, and static file serving to a more efficient process. We’re going to install Nginx and configure it to proxy requests to Umami, meaning it will take care of handing requests from your users to Umami and back again.

      First, refresh your package list, then install Nginx using apt:

      • sudo apt update
      • sudo apt install nginx

      Allow public traffic to ports 80 and 443 (HTTP and HTTPS) using the “Nginx Full” UFW application profile:

      • sudo ufw allow "Nginx Full"


      Rule added Rule added (v6)

      Next, open up a new Nginx configuration file in the /etc/nginx/sites-available directory. We’ll call ours umami.conf but you could use a different name:

      • sudo nano /etc/nginx/sites-available/umami.conf

      Paste the following into the new configuration file, being sure to replace your_domain_here with the domain that you’ve configured to point to your Umami server. This will be something like, for instance:


      server {
          listen       80;
          listen       [::]:80;
          server_name  your_domain_here;
          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 X-Real-IP $remote_addr;
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

      This configuration is HTTP-only for now, as we’ll let Certbot take care of configuring SSL in the next step. The rest of the config sets up logging locations and then passes all traffic along to http://localhost:3000, the Umami instance we started up in the previous step.

      Save and close the file, then enable the configuration by linking it into /etc/nginx/sites-enabled/:

      • sudo ln -s /etc/nginx/sites-available/umami.conf /etc/nginx/sites-enabled/

      Use nginx -t to verify that the configuration file syntax is correct:


      nginx: the configuration file /etc/nginx/nginx.conf syntax is ok nginx: configuration file /etc/nginx/nginx.conf test is successful

      And finally, reload the nginx service to pick up the new configuration:

      • sudo systemctl reload nginx

      Your Umami site should now be available on plain HTTP. Load http://your_domain_here and it will look like this:

      A screenshot of the Umami login page, with 'Username' and 'Password' textboxes

      Now that you have your site up and running over HTTP, it’s time to secure the connection with Certbot and Let’s Encrypt certificates.

      Step 3 — Installing Certbot and Setting Up SSL Certificates

      Thanks to Certbot and the Let’s Encrypt free certificate authority, adding SSL encryption to our Umami app will take only two commands.

      First, install Certbot and its Nginx plugin:

      • sudo apt install certbot python3-certbot-nginx

      Next, run certbot in --nginx mode, and specify the same domain you used in the Nginx server_name config:

      • sudo certbot --nginx -d your_domain_here

      You’ll be prompted to agree to the Let’s Encrypt terms of service, and to enter an email address.

      Afterwards, you’ll be asked if you want to redirect all HTTP traffic to HTTPS. It’s up to you, but this is generally recommended and safe to do.

      After that, Let’s Encrypt will confirm your request and Certbot will download your certificate:


      Congratulations! You have successfully enabled You should test your configuration at: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - IMPORTANT NOTES: - Congratulations! Your certificate and chain have been saved at: /etc/letsencrypt/live/ Your key file has been saved at: /etc/letsencrypt/live/ Your cert will expire on 2021-12-06. To obtain a new or tweaked version of this certificate in the future, simply run certbot again with the "certonly" option. To non-interactively renew *all* of your certificates, run "certbot renew" - Your account credentials have been saved in your Certbot configuration directory at /etc/letsencrypt. You should make a secure backup of this folder now. This configuration directory will also contain certificates and private keys obtained by Certbot so making regular backups of this folder is ideal. - If you like Certbot, please consider supporting our work by: Donating to ISRG / Let's Encrypt: Donating to EFF:

      Certbot will automatically reload Nginx to pick up the new configuration and certificates. Reload your site and it should switch you over to HTTPS automatically if you chose the redirect option.

      Your site is now secure and it’s safe to log in with the default user admin and password umami. Please do this immediately, and follow the official first login documentation to get logged in and change your admin password to something more secure.

      When you first log in, you’ll see a somewhat bare dashboard:

      A screenshot of the Umami dashboard after login, showing a

      You have successfully installed and secured your Umami analytics software. In the conclusion of this tutorial you’ll find links to documentation that will get you started with adding your site to Umami, and adding Umami tracking snippet to your site.


      In this tutorial, you launched the Umami app and a PostgreSQL database using Docker Compose, then set up an Nginx reverse proxy and secured it using Let’s Encrypt SSL certificates.

      Also, you should have logged in and updated the default password already. If not, do that now.

      Afterwards, continue with the official documentation to learn how to add a website to Umami, then start collecting data by installing the tracking code on your website.

      Source link

      How To Deploy Your Own Web Analytics Software with Umami on DigitalOcean’s App Platform

      The author selected The Mozilla Foundation to receive a donation as part of the Write for DOnations program.


      After deploying a website, you will want to add analytics scripts to your site to learn about the pages that drive the most traffic and track the number of visitors, goal conversions, and page views. Umami is an open-source web analytics software that runs on PostgreSQL and Next.js API routes.

      Umami allows you to track events, referring pages, session durations, view counts, and unique visitor counts for your pages. On a single Umami instance, you can track an unlimited number of websites and create multiple users so different people can track their websites from a single deployment.

      In this guide, you will clone Umami to your local computer, create PostgreSQL tables, set up connection pooling, and deploy Umami to App Platform.


      Before you begin this guide you’ll need the following:

      Step 1 — Forking and Cloning the Umami Repository

      The Umami repository on GitHub contains the files and scripts needed to run Umami. Forking this repository allows you to deploy Umami to App platform, and use an SQL script contained in it to set up tables in the PostgreSQL database.

      In this step, you will fork the repository and clone it to your local computer with git.

      To fork the repository, go to the Umami repository on GitHub and click the Fork button at the top right corner of the page. Your copy of the repository will be at

      In your forked repository, click the Code button, copy the HTTPS link, and clone the forked repository to your local computer with the following command:

      • git clone

      The git clone command creates a copy of a repository on your computer. You will see an output similar to the following after running the command:


      Cloning into 'umami'... remote: Enumerating objects: 6352, done. remote: Counting objects: 100% (270/270), done. remote: Compressing objects: 100% (159/159), done. remote: Total 6352 (delta 131), reused 219 (delta 103), pack-reused 6082 Receiving objects: 100% (6352/6352), 2.57 MiB | 519.00 KiB/s, done. Resolving deltas: 100% (4388/4388), done. Checking out files: 100% (355/355), done.

      Move into the repository’s directory:

      Now that you have forked the Umami repository and cloned it to your local machine, you will set up the umami database on PostgreSQL and create its tables.

      Step 2 — Creating the umami Database, Setting Up Tables, and Starting a Connection Pool

      In this step, you will create and initialize an umami database in your cluster. This database is where Umami will store data from your websites.

      To create the umami database in your cluster, open the Cloud Control Panel in your DigitalOcean account and select Databases from the side menu. Choose the database cluster you created from the list of clusters. Navigate to the Users and Databases tab and scroll down to Databases. Type umami in the textbox and click Save to create the umami database.

      Creating a database in your DigitalOcean managed database

      Now that you have created the umami database, you can build the tables Umami will need to run. To complete this, you will need the connection string to connect to your umami database.

      On the Cloud Control Panel, switch to the Overview tab. Look for the Connection Details section on the right of the page. In the dropdown where Connection Parameters is written, select Connection String. Select the umami database from the dropdown beside where Database/Pool is written. Afterward, click Copy to copy the connection string to the clipboard.

      Locating the connection string of a DigitalOcean managed database

      The SQL script at sql/schema.postgresql.sql creates all the tables that Umami needs and sets up the indices in all these tables. It also sets up an admin account for Umami with the username admin and password umami.

      Warning: The admin user on Umami can create and delete accounts. It is strongly advised to change these default credentials after deployment to prevent unauthorized access to your Umami instance. You can change the default credentials in Step 3.

      Run the following command from the umami directory you entered to create the tables:

      • psql 'your_connection_string' -f sql/schema.postgresql.sql

      psql uses the connection string to connect to your database and the -f flag runs the SQL script at sql/schema.postgresql.sql against the database.

      When you run the command successfully, you will have the following output:


      psql:sql/schema.postgresql.sql:1: NOTICE: table "event" does not exist, skipping DROP TABLE psql:sql/schema.postgresql.sql:2: NOTICE: table "pageview" does not exist, skipping DROP TABLE psql:sql/schema.postgresql.sql:3: NOTICE: table "session" does not exist, skipping DROP TABLE psql:sql/schema.postgresql.sql:4: NOTICE: table "website" does not exist, skipping DROP TABLE psql:sql/schema.postgresql.sql:5: NOTICE: table "account" does not exist, skipping DROP TABLE CREATE TABLE CREATE TABLE CREATE TABLE CREATE TABLE CREATE TABLE CREATE INDEX CREATE INDEX CREATE INDEX CREATE INDEX CREATE INDEX CREATE INDEX CREATE INDEX CREATE INDEX CREATE INDEX CREATE INDEX CREATE INDEX INSERT 0 1

      You have successfully created the umami database and the tables in it. You will now create a connection pool for the umami database.

      PostgreSQL was built to have persistent connections. The Next.js API routes that Umami runs on, however, are not able to share database connections across requests. To support the short-lived connections that will be made from the API route and prevent errors, you will create a connection pool for your cluster.

      A connection pool is an application that allows you to reuse database connections across multiple requests by making a number of persistent connections to the database and forwarding client requests through those connections. When more requests are made than connections are available, subsequent requests are queued until there is a free connection.

      To enable connection pooling for your managed database, go to your Cloud Control Panel. Click Databases on the side menu then select the database you created. Go to the Connection Pools tab and click Create a Connection Pool. A modal will open. Set the pool name as umami-pool, select the umami database, and set the pool size to 11. Click Create Pool to create the connection pool.

      You can change the size of the connection pool later to support more traffic. Refer to How to Manage Connection Pools to learn more about when to adjust and how to select a pool size.

      Requests from Umami will not be made directly to the database but to the connection pool. You will therefore need the connection string of the connection pool. This connection string is one of the environment variables that will be needed when deploying the app to the App Platform. To get the connection string, go to the Connection Pools tab and click Connection details. When the modal opens, click the Connection parameters dropdown, select Connection String, and click Copy to copy the connection string.

      The connection pool’s connection string is one of the environment variables you will need when deploying to the App Platform since database requests will be made to the connection pool.

      Now that you have set up connection pooling on your database, you will deploy Umami to the App Platform.

      Step 3 — Deploying Umami to App Platform

      In this step, you will deploy Umami to App Platform. Umami runs on a web application written in Next.js, and App Platform will deploy it from your fork of Umami. Visit the App Platform section of the Control Panel and click Launch Your App to begin.

      You will be presented with a list of options for the source of your code. Choose GitHub as the source. If this is your first time deploying to App Platform from a GitHub repository, you will be asked to connect App Platform to your GitHub account.

      Choose the repository where you want to deploy your app. Select your_github_username/umami as the source repository from the dropdown. Leave the branch as master, keep Autodeploy code changes checked, then click Next.

      Selecting a GitHub repository to deploy to App Platform from

      App Platform will automatically detect a Dockerfile in the repository and set the necessary settings. You will now add the environment variables that Umami requires.

      Umami requires two environment variables to work:

      • DATABASE_URL: the connection string for your PostgreSQL database.
      • HASH_SALT: a random string used to generate unique values for the application.

      Click Edit next to Environment Variables to add these environment variables.

      For Umami to work well with your connection pool, you will need to modify the connection pool connection string you got from the Cloud Control Panel by appending &pgbouncer=true to the end. The value of DATABASE_URL should look like:


      Click the + button and set a HASH_SALT environment variable as a random string. Tick the Encrypt checkbox next to HASH_SALT so the value of HASH_SALT will be encrypted while saving.

      Setting environment variables while deploying Umami to App Platform

      Click Next to continue setting up the app.

      Pick a name for your Umami instance and select the region where to deploy your app. The region closest to you is automatically selected to minimize connection latency. Click Next to proceed.

      Select the Basic plan, or the Pro plan should you require a larger size for your project, and click Launch Your App to finalize the deployment.

      The app build will now begin. Once the build completes, the URL where your app will be accessible will display under the app’s name.

      Open the URL to visit your analytics dashboard.

      Umami analytics dashboard

      You can log in with the default credentials:

      • Username: admin
      • Password: umami

      Secure your instance by clicking Settings on the header. Navigate to Profile on the sidebar and click Change password. Enter the previous password—umami and pick a new password for signing in to the admin account.

      To get the tracking script for a website, log in to your Umami Dashboard. Select Settings on the navigation bar at the top of the screen. Click the Add website button. When the modal opens, select a name for the website and enter the domain where the website is located.

      Adding a website to Umami

      After adding the website, you will find it in the list of websites in the settings. Click the first button under the website to show the tracking script.

      Finding the tracking script for a website on Umami

      When you click the button, a modal will open with the tracking script in a <script> tag. Paste the code snippet shown in the <head> tag of your website’s pages to start getting data from the website. When a visitor visits your web pages, the script automatically sends data to Umami.


      You have now successfully deployed your instance of Umami Analytics. You can now track page views, session durations, and other metrics from all your websites. You can refer to Umami’s documentation to learn how to track events. If you want to have Umami available from a custom domain, you can refer to How to Manage Domains in App Platform to learn how.

      Source link