This guide walks through a self-hosted installation of Umami. With the release of Umami v3 (December 2024), note that PostgreSQL is now the only supported database - MySQL support has been removed.
For Docker installation, see Docker.
Install Git and other required tools to clone the project repository.
# On Debian/Ubuntu
sudo apt-get update && sudo apt-get install -y git curl wget
# On RHEL/CentOS/Fedora
sudo dnf install -y git curl wget
Before installing Umami, ensure PostgreSQL is available. You can either:
For a Docker-based PostgreSQL setup:
mkdir -p ~/umami-db
docker run -d \
--name umami-db \
-e POSTGRES_DB=umami \
-e POSTGRES_USER=umami \
-e POSTGRES_PASSWORD=your_secure_password \
-v ~/umami-db:/var/lib/postgresql/data \
-p 5432:5432 \
postgres:15-alpine
Download the source code to the server. For production, specify a specific version tag instead of the main branch.
# Clone the repository
git clone https://github.com/umami-software/umami umami
# Navigate to the directory
cd umami
# Check available tags to select a specific version
git tag -l | sort -V
# For production, checkout a specific version (e.g., latest stable)
git checkout v3.0.3 # Replace with latest stable version
Create and customize the environment configuration file:
# Copy the example environment file
cp .env.example .env
# Edit the .env file with your specific settings
nano .env
Essential environment variables for Umami v3:
# Database configuration (PostgreSQL only in v3)
UMAMI_DB_TYPE=postgresql
UMAMI_DB_HOST=your-postgres-host
UMAMI_DB_PORT=5432
UMAMI_DB_USER=umami
UMAMI_DB_NAME=umami
UMAMI_DB_PASSWORD=your_secure_password
# Application settings
UMAMI_APP_SECRET=generate_a_random_secret_here
UMAMI_URL=https://analytics.yourdomain.com
Before starting Umami, initialize the database schema:
# Build and run the container to initialize the database
docker compose run --rm app npm run db:reset
# Or if using a specific version tag, you may need to pull the image first
docker compose pull
Use Docker Compose to start services in the background.
docker compose up -d
Check that all services are running properly:
# Check container status
docker compose ps
# View logs to confirm successful startup
docker compose logs app
# Verify the application is accessible (replace with your domain/IP)
curl -I http://localhost:3000
http://your-server-ip:3000 or your configured domainadmin / umamiPrefer automation? See Umami Ansible Setup for an example playbook.
Prefer containers? See Umami Docker Setup.
⚠️ Umami v3 Breaking Changes:
Common issues and solutions:
Any questions?
Feel free to contact us. Find all contact information on our contact page.