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