Umami - Developer Guide

Learn how to deploy Umami on AWS with our step-by-step guide. It walks you through launching the Meetrix Umami AMI with CloudFormation, pointing your domain at it, logging in for the first time, adding the tracking code to your website, and keeping the server healthy once it runs.

Umami is an open-source, privacy-focused web analytics platform. It shows page views, visitors, referrers and custom events on one clean dashboard, without cookies and without sending your visitors' data to a third party. Running it on your own AWS account means the analytics database belongs to you. If you publish with Ghost, our Ghost developer guide sets up a blog you can track with Umami on the same cloud, and the Coolify developer guide covers a self-hosted platform for deploying the sites themselves.

Launching the AMI

Step 1: Find and Select Umami AMI

1. Log in to your AWS Management Console.
2. Navigate to 'Umami' in AWS Marketplace.

Step 2: Initial Setup & Configuration

1. Click the "Continue to Subscribe" button.
2. After subscribing, accept the terms and click "Accept Terms".
3. Wait a few minutes until processing completes, then click "Continue to Configuration".
4. Select "CloudFormation script to deploy Umami" as the fulfillment option and choose your region. Click "Continue to Launch".
5. From the "Choose Action" dropdown, select "Launch CloudFormation" and click "Launch".

Create CloudFormation Stack

Step 1: Create a stack

1. Ensure the "Template is ready" option is selected under "Prepare template".
2. Click "Next".

Step 2: Specify stack options

1. Provide a unique "Stack name".
2. Enter the "AdminEmail" used for SSL certificate generation.
3. Enter an "AdminPassword". This is the password for the Umami admin account you log in with, so store it securely.
4. Enter a value for "DeploymentName".
5. Provide a public domain for "DomainName". Umami will automatically try to set up SSL if the domain is hosted on Route 53. If unsuccessful, you must set up SSL manually.
6. Choose an instance type "InstanceType" (Recommended: t3a.small).
7. Select your preferred "KeyName".
8. Enter the name of your S3 bucket for "S3Bucket", used for storing backups.
9. Set "SSHLocation" to 0.0.0.0/0, or restrict it to your own IP range.
10. Keep "SubnetCidrBlock" as 10.0.0.0/24.
11. Keep "VpcCidrBlock" as 10.0.0.0/16.
12. Click "Next".

Step 3: Configure stack options

1. Choose "Roll back all stack resources" and "Delete all newly created resources" under "Stack failure options".
2. Click "Next".

Step 4: Review

Review and verify the parameters you've entered.

1. Tick "I acknowledge that AWS CloudFormation might create IAM resources with custom names".
2. Click "Submit".

Afterward, you'll be directed to the CloudFormation stacks page. Please wait 5-10 minutes until the stack status shows CREATE_COMPLETE.

Update DNS

Step 1: Copy IP Address

Copy the public IP labeled "PublicIp" in the "Outputs" tab.

Step 2: Update DNS

1. Go to AWS Route 53 and navigate to "Hosted Zones".
2. Click Create record.
3. Add a record name matching the DomainName you entered, keep the record type as A, and paste the copied PublicIp into the value textbox.
4. Click "Create records".

Access Umami

Access Umami using the "DashboardUrl" in the Outputs tab. Until DNS and SSL are in place you can use "DashboardUrlIp" instead, which serves the dashboard over plain HTTP.

On the login screen, enter the username admin and the AdminPassword you set in the stack parameters, then click "Login".

After logging in you land on the Websites page, which stays empty until you add your first site.

Add Your First Website

1. On the Websites page, click "Add website".
2. Enter a Name (usually the site's domain) and the site's Domain, then click "Save".
3. Click "Edit" on the new website and open its Tracking code section.
4. Copy the snippet and paste it into the <head> of every page you want to track.

The snippet looks like this, with your own Umami domain and website ID filled in:

<script defer src="https://<your Umami domain>/script.js" data-website-id="<your website ID>"></script>

Visit your site once, and the visit appears on the Umami dashboard within a few seconds. The official guides to adding a website and collecting data cover framework-specific setups and custom event tracking.

Generate SSL Manually

Umami will automatically try to set up SSL when a Route 53-hosted domain is provided. If it fails, follow these steps to generate SSL manually.

Step 1: Copy IP Address

1. Follow the Update DNS steps above, if not already done.
2. Copy the Public IP indicated as "PublicIp" in the "Outputs" tab.

Step 2: Log in to the server

1. Open the terminal and go to the directory where your private key is located.
2. Run the following command, replacing the key name and IP address.
3. Type "yes" and press Enter to confirm.

ssh -i <your key name> ubuntu@<Public IP address>

Step 3: Generate SSL

Run the following command and follow the prompts:

sudo /root/certificate_generate_standalone.sh

Once the certificate is in place, update the tracking snippet on your websites to load script.js over https. Browsers block an http script on an https page, so tracking silently stops otherwise.

Check Server Logs

Step 1: Log in to the server

ssh -i <your key name> ubuntu@<Public IP address>

Step 2: Check the logs

List the running containers, then view the logs of a container using the first few characters of its container ID. Umami runs alongside a PostgreSQL database, so check both containers if the dashboard does not load:

sudo docker ps

sudo docker logs <container-id-prefix>

Shutting Down Umami

1. In CloudFormation, click the link labeled "Instance" in the "Resources" tab to open the EC2 instance.
2. Stop the Umami instance from the Instance state dropdown. You can restart it later as needed.

Remove Umami

Delete the CloudFormation stack from the AWS Management Console under "CloudFormation Stacks" by clicking "Delete".

Upgrades

When a new version is available in AWS Marketplace, remove the previous deployment after backing up necessary server data, and relaunch with the new version.

Troubleshoot

If you face vCPU quota limits, request an increase: How to increase AWS quota.

If you face insufficient capacity errors while creating the stack, try another region or time.

If the dashboard shows a 502 Bad Gateway error, wait 5-10 minutes and retry. Umami can take a few minutes to start after the instance boots.

If the dashboard loads but no visits appear, open your website with the browser's developer tools and check that script.js loads from your Umami domain. Ad blockers and privacy extensions often block analytics scripts, so test from a browser without them.

Check whether the instance storage is full. Log into the server and run:

df -h

If the root volume is between 90-100%, resize the EBS volume, then reboot and restart the service.

Conclusion

The Meetrix Umami Deployment Guide helps you run privacy-focused web analytics in your AWS environment, with the data in a database you control. Whether you're a DevOps engineer, developer, or marketing lead, this guide provides step-by-step instructions for a secure setup. See the Umami store page for what the Meetrix image includes. Umami tells you who visits your websites; for metrics on the servers behind them, our Grafana developer guide sets up monitoring dashboards on AWS. The source code and release notes are on GitHub.

Technical Support

Reach out to Meetrix Support (aws@meetrix.io) for assistance with Umami issues.