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:
- 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:
- 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:
- Install Node.js, PostgreSQL, and Git:
sudo apt update
sudo apt install -y nodejs npm postgresql git
- Clone the Umami repository:
git clone https://github.com/umami-software/umami.git
cd umami
- Install dependencies and build the project:
npm install
npm run build
- 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:
- Create a new Nginx configuration file:
sudo nano /etc/nginx/sites-available/umami
- 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;
}
}
- 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.