Self-Hosting Umami: Your Modern, Privacy-Focused Analytics Alternative
As a software engineer, you're constantly looking for ways to improve your applications. Umami provides the data you need to do that effectively, without the complexity and privacy concerns of other analytics platforms.
Here’s why it's so useful
You Own Your Data
Umami is self-hosted, meaning you control where your data lives. This is a huge advantage for security and compliance, especially if you're working with sensitive user information. You can host it on your own server or a private cloud.
Privacy-First Design
It’s a modern, privacy-focused solution. Umami doesn't use cookies and anonymizes all data, which helps you comply with regulations like GDPR and CCPA. As an engineer, this means less time worrying about legal complexities and more time building.
Lightweight and Fast
The tracking script is tiny—just a few kilobytes. This means it won't slow down your website, which is crucial for user experience and SEO.
Open Source
Being open source gives you the freedom to inspect the code, understand exactly how it works, and even contribute to its development. You can also customize it to fit your specific needs.
Simple, Clear Interface
The dashboard is clean and easy to understand. You get the key metrics you need—page views, unique visitors, referrers, and more—without being overwhelmed by complex reports.
There are a few ways to deploy Umami, but a popular method for engineers is using Docker, as it's efficient and portable.
Install Docker and Docker Compose
Make sure you have both installed on your server.
Clone the Repository
git clone https://github.com/umami-software/umami.git
cd umami
Configure Your Environment
Copy the example environment file.
cp .env.example .env
Then, open the .env file and set a DATABASE_URL and TRACKER_SCRIPT_NAME. You can use a PostgreSQL or MySQL database. For a simple setup, you can use the provided docker-compose.yml with a PostgreSQL container.
Run with Docker Compose
docker-compose up -d
This command will build and start the Umami server and the database container in the background.
If you're already using Vercel, you can deploy Umami directly from its GitHub repository. This is great for a quick, serverless setup. You'll still need to provide a database, like a managed PostgreSQL service (e.g., from Vercel's integrations).
Once Umami is running, you'll need to add the tracking script to your website.
Get Your Tracking Code
After you've deployed Umami and added a website in the dashboard, you'll get a tracking code snippet. It will look something like this
<script async src="https://your-umami-domain.com/script.js" data-website-id="YOUR_WEBSITE_ID"></script>
Add to Your HTML
Place this script tag in the <head> section of your website's HTML, right before the closing </head> tag.
If you're using a framework like React, you can add this script to your index.html file or use a library to manage it.
In public/index.html
<!DOCTYPE html>
<html lang="en">
<head>
<title>My React App</title>
<script async defer data-website-id="YOUR_WEBSITE_ID" src="https://your-umami-domain.com/script.js"></script>
</head>
<body>
<noscript>You need to enable JavaScript to run this app.</noscript>
<div id="root"></div>
</body>
</html>
For SPAs, Umami automatically tracks page views when the URL changes. If you need to trigger a manual event, you can use the umami.track() function.
Let's say you want to track a button click
// Function to handle the button click
function handleClick() {
console.log('Button clicked!');
// Send a custom event to Umami
window.umami.track('contact-button-click');
}
// Add an event listener to the button
document.getElementById('contactButton').addEventListener('click', handleClick);
You can then see this custom event in your Umami dashboard.
