Umami is a Next.js analytics app typically backed by PostgreSQL (Umami v3 requires PostgreSQL only). Security posture depends on strong app secrets, protected admin access, and private database networking. With the release of Umami v3 (December 2024), note that security considerations have evolved with the new architecture.
¶ 1) Protect Application Secrets and Authentication
- Set strong random
UMAMI_APP_SECRET in environment (minimum 32 characters recommended)
- Generate secure hash salt with
openssl rand -hex 32 for UMAMI_HASH_SALT
- Store secrets using Docker secrets or Kubernetes secrets in production
- Rotate app secrets regularly and when credentials are exposed
- Enforce strong admin credentials (minimum 12 characters with mixed case, numbers, symbols)
- Disable default accounts immediately after initial setup
- Restrict who can create websites/users in Umami (configure user roles appropriately)
- Implement MFA for admin accounts if possible
- Regularly audit user accounts and permissions
¶ 2) Database Security and Network Hardening
- Keep DB reachable only from Umami host/container network (use internal networks)
- Enforce DB authentication with strong passwords and connection limits
- Use TLS encryption for DB connections (
sslmode=require for PostgreSQL)
- Store env/config files with restrictive permissions (600 or 400)
- Implement database user with minimal required privileges
- Use container networks to isolate Umami from other services
- Implement firewall rules to restrict database access to Umami containers only
- Use VPN or private networks for database connections in distributed setups
¶ HTTPS and TLS
- Enforce HTTPS for all script and dashboard access
- Use HSTS headers to prevent downgrade attacks
- Implement proper certificate management and renewal
- Use TLS 1.2+ with strong cipher suites
¶ Rate Limiting and DDoS Protection
- Set reverse-proxy rate limits on tracker endpoint (recommend 100 requests/minute per IP)
- Implement connection limits at the proxy level
- Use WAF (Web Application Firewall) if available
- Configure application-level rate limiting where possible
¶ CORS and Origin Restrictions
- Restrict CORS and host/origin settings to trusted domains only
- Implement proper referer validation
- Use Content Security Policy (CSP) headers
- Validate and sanitize all inputs
- Use official Umami images from GHCR.io
- Pin to specific version tags (e.g.,
ghcr.io/umami/umami:postgresql-v3.0.3) instead of latest
- Scan container images for vulnerabilities regularly
- Run containers with non-root user where possible
- Implement resource limits to prevent DoS
- Use read-only root filesystem where possible
- Mount secrets and config files with appropriate permissions
- Disable unnecessary capabilities
¶ 5) Monitoring and Logging
- Monitor unusual traffic bursts and failed login patterns
- Log all authentication attempts and access to sensitive areas
- Implement anomaly detection for unusual usage patterns
- Monitor database access logs for suspicious queries
- Enable detailed logging for administrative actions
- Log all changes to tracking configurations
- Maintain logs of user creation/deletion activities
- Implement centralized log aggregation and analysis
With the release of Umami v3 (December 2024), pay special attention to:
- Database Migration: Securely migrate from MySQL to PostgreSQL if upgrading from v2
- New UI Security: Review new interface elements for potential security implications
- API Changes: Verify that any custom integrations comply with new API structure
- Permissions: Check that user roles and permissions work as expected in the new UI
¶ Verification Commands
# Check for exposed secrets in environment files
grep -E 'UMAMI_APP_SECRET|UMAMI_DB_PASSWORD|UMAMI_HASH_SALT' /opt/umami/.env
# Verify listening ports and services
sudo ss -tulpn | grep -E ':3000|:443|:5432'
# Check container logs for security-related events
docker compose -f /opt/umami/docker-compose.yml logs --tail=200 | grep -Ei 'auth|error|forbidden|denied|failed'
# Check file permissions on sensitive files
ls -la /opt/umami/.env
# Verify container runs with appropriate user
docker exec -it umami-app whoami
# Check for any exposed credentials in running containers
docker inspect umami-app | grep -i password
- Umami docs: https://umami.is/docs
- Umami self-hosting docs: https://umami.is/docs/getting-started/installation
- Umami repository and advisories: https://github.com/umami-software/umami/security
- PostgreSQL security guidelines: https://www.postgresql.org/docs/current/security.html
- OWASP Web Application Security Testing Checklist