This guide uses Docker Compose to run 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.
Create a dedicated directory for Umami and navigate to it:
mkdir -p ~/umami && cd ~/umami
Create an .env file with your configuration:
# Create environment file
touch .env
# Edit the file with your preferred editor
nano .env
Add the following configuration (update values as needed):
# Database Configuration (PostgreSQL only in Umami 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_strong_random_secret_here
UMAMI_URL=https://analytics.yourdomain.com
# Optional Settings
UMAMI_RESET_TIMEZONE=UTC
UMAMI_DISABLE_COOKIE=true
Create a docker-compose.yml file:
version: '3.8'
services:
umami:
image: ghcr.io/umami/umami:postgresql-v3.0.3 # Pin to specific version
restart: unless-stopped
ports:
- "3000:3000"
environment:
- DATABASE_URL=postgresql://${UMAMI_DB_USER}:${UMAMI_DB_PASSWORD}@${UMAMI_DB_HOST}:${UMAMI_DB_PORT}/${UMAMI_DB_NAME}
- APP_SECRET=${UMAMI_APP_SECRET}
- UMAMI_URL=${UMAMI_URL}
depends_on:
- db
healthcheck:
test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:3000/api/website"]
interval: 30s
timeout: 10s
retries: 3
db:
image: postgres:15-alpine
restart: unless-stopped
environment:
- POSTGRES_DB=${UMAMI_DB_NAME}
- POSTGRES_USER=${UMAMI_DB_USER}
- POSTGRES_PASSWORD=${UMAMI_DB_PASSWORD}
volumes:
- umami-db-data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${UMAMI_DB_USER} -d ${UMAMI_DB_NAME}"]
interval: 10s
timeout: 5s
retries: 5
volumes:
umami-db-data:
Before starting Umami, initialize the database schema:
# Pull the latest image
docker compose pull
# Initialize the database
docker compose run --rm umami npx prisma migrate deploy
Start the services in detached mode:
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 umami
# Verify the application is accessible
curl -I http://localhost:3000
Use Specific Version Tags: Always use specific version tags instead of latest:
image: ghcr.io/umami/umami:postgresql-v3.0.3
Secure Environment Files: Set restrictive permissions on your .env file:
chmod 600 .env
Network Isolation: Consider using an isolated network for your containers:
services:
umami:
networks:
- umami-network
db:
networks:
- umami-network
networks:
umami-network:
driver: bridge
If you’re using an external PostgreSQL server, remove the db service from your compose file:
version: '3.8'
services:
umami:
image: ghcr.io/umami/umami:postgresql-v3.0.3
restart: unless-stopped
ports:
- "3000:3000"
environment:
- DATABASE_URL=postgresql://${UMAMI_DB_USER}:${UMAMI_DB_PASSWORD}@${UMAMI_DB_HOST}:${UMAMI_DB_PORT}/${UMAMI_DB_NAME}
- APP_SECRET=${UMAMI_APP_SECRET}
healthcheck:
test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:3000/api/website"]
interval: 30s
timeout: 10s
retries: 3
To update to a newer version:
docker-compose.ymldocker compose pulldocker compose up -dRegular maintenance tasks:
# View logs
docker compose logs umami
# Restart services
docker compose restart
# Stop services
docker compose down
# View resource usage
docker stats
postgresql-v3.0.3)Any questions?
Feel free to contact us. Find all contact information on our contact page.