Umami Analytics: The Ultimate Self-Hosting Setup

Umami Analytics is an open-source, privacy-focused web analytics platform that allows developers and organizations to track website performance without relying on third-party tools like Google Analytics. By self-hosting Umami Analytics, users retain full control over their data while enjoying a lightweight, customizable, and easy-to-use solution. This guide covers the core steps to deploy, configure, and manage Umami Analytics, including installation, reverse proxy setup, logging, backups, updates, and advanced features.

Installing Umami Analytics

📦 Docker/Docker Compose Setup

Docker is the most efficient way to deploy Umami Analytics. Below is an optimized docker-compose.yml file tailored to Umami:

1. Create a docker-compose.yml file:

version: '3.8'

services:

umami:

image: ghcr.io/umami-software/umami:latest

container_name: umami

ports:

- "3000:3000"

environment:

DATABASE_URL: "postgresql://umami:umami_password@db:5432/umami"

HASH_SALT: "your_random_salt_value"

depends_on:

- db

db:

image: postgres:13-alpine

container_name: umami-db

environment:

POSTGRES_USER: umami

POSTGRES_PASSWORD: umami_password

POSTGRES_DB: umami

volumes:

- umami-db-data:/var/lib/postgresql/data

volumes:

umami-db-data:

2. Deploy the stack:

docker-compose up -d

This will start Umami Analytics on port 3000 and set up a Postgres database for storage.

🚀 Manual Installation

For those who prefer a manual installation on Linux:

1. Install Node.js, PostgreSQL, and Git:

sudo apt update

sudo apt install -y nodejs npm postgresql git

2. Clone the Umami repository:

git clone https://github.com/umami-software/umami.git

cd umami

3. Install dependencies and build the project:

npm install

npm run build

4. Configure the database and start the server:

sudo -u postgres psql -c "CREATE DATABASE umami;"

sudo -u postgres psql -c "CREATE USER umami WITH ENCRYPTED PASSWORD 'umami_password';"

sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE umami TO umami;"

DATABASE_URL=postgresql://umami:umami_password@localhost:5432/umami npm start

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration

To make Umami Analytics accessible via a domain, create an Nginx server block:

1. Create a new Nginx configuration file:

sudo nano /etc/nginx/sites-available/umami

2. Add the following configuration:

server {

server_name analytics.example.com;

location / {

proxy_pass http://localhost:3000;

proxy_http_version 1.1;

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection 'upgrade';

proxy_set_header Host $host;

proxy_cache_bypass $http_upgrade;

}

}

3. Enable the configuration and reload Nginx:

sudo ln -s /etc/nginx/sites-available/umami /etc/nginx/sites-enabled/

sudo nginx -t

sudo systemctl reload nginx

🔒 SSL/TLS Setup

Secure your site with Let's Encrypt:

sudo apt install certbot python3-certbot-nginx

sudo certbot --nginx -d analytics.example.com

sudo systemctl reload nginx

Logging and Debugging Umami Analytics

🗃️ Enabling Debug Logs

Modify the LOG_LEVEL environment variable in your docker-compose.yml or system setup to enable debug logs:

environment:

LOG_LEVEL: "debug"

📄 Viewing Logs

For Docker deployments:

docker logs -f umami

For manual installations:

tail -f /path/to/your/logs/umami.log

🛠️ Troubleshooting Common Issues

If Umami doesn’t start, check the following:

• Ensure the DATABASE_URL is correctly configured.

• Verify Nginx settings with sudo nginx -t.

📤 Exporting Logs

To forward logs to an ELK stack, configure a logging driver in Docker:

logging:

driver: "gelf"

options:

gelf-address: "udp://your-elk-server:12201"

Backup and Restore

🗂️ File-Based Backups

Backup your docker-compose.yml and configuration files:

tar -czvf umami-backup.tar.gz ./docker-compose.yml ./config

🔄 Database Backups

Export the PostgreSQL database:

docker exec -t umami-db pg_dumpall -c -U umami > umami-db-backup.sql

Restore the database:

cat umami-db-backup.sql | docker exec -i umami-db psql -U umami

📅 Automated Backup Scripts

Schedule periodic backups using a cron job:

crontab -e

Add the following line:

0 3 * * * docker exec -t umami-db pg_dumpall -c -U umami > /path/to/backups/umami-$(date +\%F).sql

Updating and Upgrading Umami Analytics

⬆️ Updating Docker Images

Pull the latest Docker image and recreate the containers:

docker-compose pull

docker-compose up -d

🛠️ Manual Updates

For manual installations:

git pull

npm install

npm run build

npm start

🔍 Checking for Updates

Monitor the official GitHub repository for release notes:

git remote show origin

Leveraging Umami Analytics’s Unique Features

🔧 Enabling APIs

Activate the API by ensuring the server is running and test the endpoint:

curl -X GET http://localhost:3000/api/stats

🌟 Advanced Configurations

Integrate webhooks or third-party tools by editing your environment variables to include:

WEBHOOK_URL="https://your-service.com/webhook"

Wrapping Up

Self-hosting Umami Analytics empowers users with complete ownership of their data while offering a lightweight, privacy-first analytics solution. By following this guide, you’ve deployed, secured, and optimized Umami Analytics for production use. Now you can take full advantage of its features to gain insights into your website’s performance with total control.