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.

Introduction

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.

Prerequisites

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

• A DigitalOcean account. To create a new account, navigate to the DigitalOcean sign up page.
• A GitHub account. You can create an account from the GitHub sign up page.
• Git installed on your local machine. You can follow the tutorial Contributing To Open Source: Getting Started with Git to install and set up Git on your computer.
• A managed PostgreSQL database cluster. The steps to create one are described in the How To Create PostgreSQL Database Clusters page in DigitalOcecan’s documentation.
• PostgreSQL command-line client, psql, installed on your local machine. You can install psql by following the steps in the Connecting to a managed PostgreSQL section of the How To Connect to a Managed Database guide.

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 https://github.com/your\_github\_username/umami.

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 https://github.com/your_github_username/umami.git

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:

Output
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:

cd umami

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.

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.

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.

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:

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.

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:

postgres://sammy:your_password@host-domain:25061/umami?sslmode=require&pgbouncer=true

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.

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.

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.

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.

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.

Conclusion

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.