Why self-host Umami analytics?
Umami is an open-source web and product analytics platform. It brings traffic, campaigns, events and conversion reporting into a browser dashboard, with a self-hosted option for teams that want to operate their own analytics infrastructure. It is a practical Google Analytics alternative to evaluate around the reports you actually use. Explore the official Umami project.
Understand acquisition
Look at the pages and campaigns that bring visitors to your website, then check what those visitors do next.
Measure useful actions
Build a small measurement plan around actions such as a contact request, a documentation visit or a completed signup.
Operate your own data store
Choose the server location, control dashboard access and include the analytics database in your recovery planning.
Umami 3.5.0 was released on 12 November 2026. It adds browser error tracking, improves replay navigation and strengthens account and sharing controls. This guide pins that release and covers its required application secret. Read the 3.5.0 release notes.
Choose a VPS for Umami and PostgreSQL
For a few modest-traffic websites, our starting recommendation is a VPS with about 2 vCPU and 2 GB RAM. Treat this as an initial sizing choice and monitor memory, database growth and query times. Larger traffic volumes, long retention and additional analytics features need more capacity.
Use a current Ubuntu LTS server with Docker Engine and the Compose plugin installed. The commands assume your administrator can access Docker. Use sudo consistently for Docker commands if your installation requires it. This walkthrough runs Caddy directly on the host.
1. Create the deployment and secrets
Create a new deployment directory and generate three independent secrets. These commands create a fresh .env for this installation.
docker version
docker compose version
mkdir -p ~/umami
cd ~/umami
umask 077
printf 'POSTGRES_PASSWORD=%s\nAPP_SECRET=%s\nTWO_FACTOR_ENCRYPTION_KEY=%s\n' \
"$(openssl rand -hex 32)" \
"$(openssl rand -hex 32)" \
"$(openssl rand -hex 32)" > .env
chmod 600 .env
APP_SECRET secures authentication tokens and is required by Umami 3.5.0. Keep the generated value with the deployment's recovery records and retain it across normal updates. The example also disables optional application telemetry. Review the environment settings.
2. Define the Docker Compose services
Save the following as compose.yaml. It adapts the version-matched upstream stack with a pinned application image, generated database credentials and a loopback-only application port. PostgreSQL is reached over the container network. Compare the upstream Compose file.
name: umami
services:
umami:
image: docker.umami.is/umami-software/umami:3.5.0
init: true
restart: unless-stopped
ports:
- "127.0.0.1:3000:3000"
environment:
DATABASE_URL: postgresql://umami:${POSTGRES_PASSWORD:?Set the database password}@db:5432/umami
APP_SECRET: ${APP_SECRET:?Set APP_SECRET in .env}
TWO_FACTOR_ENCRYPTION_KEY: ${TWO_FACTOR_ENCRYPTION_KEY:?Set the 2FA encryption key}
DISABLE_TELEMETRY: "1"
HOSTNAME: "0.0.0.0"
depends_on:
db:
condition: service_healthy
healthcheck:
test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:3000/api/heartbeat"]
interval: 30s
timeout: 10s
retries: 5
start_period: 60s
db:
image: postgres:15-alpine
restart: unless-stopped
environment:
POSTGRES_DB: umami
POSTGRES_USER: umami
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set the database password}
TZ: UTC
volumes:
- db-data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 10s
timeout: 5s
retries: 5
volumes:
db-data:
Use a current Docker Engine for localhost publishing. In this layout the host's Caddy service reaches Umami through 127.0.0.1:3000, while public access uses HTTPS. Review Docker's port-publishing behaviour.
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 umami
curl --fail --retry 12 --retry-connrefused --retry-delay 5 \
http://127.0.0.1:3000/api/heartbeat
The heartbeat request retries while the initial database setup and application startup finish. If it still fails, inspect the service logs before continuing. Umami supports PostgreSQL, and its installation documentation recommends UTC for consistent timestamps. Review the installation requirements.
3. Secure the administrator before public access
On your own computer, open an SSH tunnel to the VPS. Replace the username and server address with your connection details.
ssh -N -L 3300:127.0.0.1:3000 admin@YOUR_VPS_IP
Keep that terminal open and visit http://localhost:3300. The initial login is admin with password umami. Version 3.5.0 requires replacing the default password before continuing. Set a unique password and verify it works. Read the first-login guide.
Enable two-factor authentication under Settings, then Security. The Compose configuration supplies the required encryption key. Keep that key and your single-use recovery codes in your recovery records. Losing or changing the encryption key makes stored two-factor secrets unreadable. Review two-factor setup.
4. Add a hostname and HTTPS with Caddy
Create an A record for analytics.example.com pointing to the VPS. Publish an AAAA record when the IPv6 route is working. Replace this example hostname wherever it appears below. Install Caddy using its official Ubuntu package instructions, then add this site block to /etc/caddy/Caddyfile, retaining any existing sites. Follow Caddy installation.
analytics.example.com {
reverse_proxy 127.0.0.1:3000
}
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
Allow inbound TCP 80 and 443 through the applicable firewalls, with SSH access restricted to your administrators. Caddy can obtain a public certificate when the hostname resolves to the server and those ports reach it. Visit the HTTPS address and verify your administrator login. Review Caddy's HTTPS reverse proxy.
5. Add your website and verify collection
Open Websites in the Umami sidebar, choose Add website and enter its name and domain. Save the website, then open its editing controls to obtain the generated tracking code. Follow the website setup guide.
Copy that code into the tracked website's <head>. Its structure looks like the following example. Replace the hostname and website ID with the generated values.
<script
defer
src="https://analytics.example.com/script.js"
data-website-id="REPLACE_WITH_YOUR_WEBSITE_ID"
></script>
Visit a tracked page and check the browser's Network panel for the script and collection requests. Verify a new visit appears in Umami. Ad blockers can prevent collection, so test with a browser profile where the tracker is allowed. Websites with a Content Security Policy also need the analytics origin permitted for script and connection requests. Read the collection guide. Review CSP connection rules.
Your website can run on HYEHOST Shared Hosting, Reseller Hosting or another platform while Umami runs on a VPS. Add its script through your site's supported theme, template or integration method. The visitor's browser needs access to the tracker and collection endpoint, so design dashboard-access restrictions around that requirement.
Use Umami 3.5 browser error tracking
To enable the new error tracking, add data-errors="true" to the tracking script. Umami then records uncaught JavaScript exceptions and unhandled promise rejections under the website's Errors tab. Optional release and environment attributes help investigate which deployment is affected. Review error tracking configuration.
<script
defer
src="https://analytics.example.com/script.js"
data-website-id="REPLACE_WITH_YOUR_WEBSITE_ID"
data-errors="true"
data-release="website-2026-11-17"
data-environment="production"
></script>
Start with a staging page and a known test error, then check that its release label appears correctly. Review event names, page URLs and error messages as part of deciding which data your application should send.
Back up analytics before updating
Keep the PostgreSQL data, compose.yaml, .env and Caddy configuration in your recovery plan. A database dump provides a consistent logical copy while PostgreSQL is running. From the deployment directory, create a restricted backup file and review the command's exit status.
umask 077
docker compose exec -T db pg_dump -U umami -d umami -Fc \
> "umami-$(date -u +%Y%m%dT%H%M%SZ).dump"
Retain encrypted copies away from the live VPS and test restoring a dump into an isolated database. Include the application secret and two-factor key in recovery records. Review PostgreSQL dump and restore guidance.
Read the target release notes, make a recoverable backup and edit the pinned Umami image tag when planning an upgrade. Pull and recreate the application, then check login, collection and reports. Version 3.5.0 applies a database migration during container startup. A rollback can require restoring pre-upgrade database state. Follow the update guidance.
docker compose config --quiet
docker compose pull umami
docker compose up -d umami
docker compose logs --tail=100 umami
Review database growth periodically. Self-hosted Umami retains analytics until you delete them, so include retention decisions in your storage planning. Read the self-hosting FAQ.
Common Umami Docker setup problems
Startup reports a missing APP_SECRET
Check that the generated secret exists in the deployment's .env and reaches the application container. Validate quietly and recreate the service after configuration changes.
The dashboard stays empty
Check the website ID, tracker URL, browser blocking and Content Security Policy. Confirm the tracked page can reach your public analytics hostname.
Database health or migrations fail
Inspect both service logs. Confirm database credentials match the existing database, check free disk space and follow the target release's migration guidance.
Self-hosted Umami analytics FAQ
Can I self-host Umami with Docker?
Yes. This guide runs Umami 3.5.0 and PostgreSQL with Docker Compose. It uses a versioned application image, persistent database storage and a host-installed HTTPS reverse proxy.
How much RAM should I choose for a small Umami VPS?
Our starting recommendation for a few modest-traffic websites is about 2 GB RAM and 2 vCPU. Monitor memory, database growth and reporting performance, then add capacity around your workload.
Why does Umami 3.5 require APP_SECRET?
APP_SECRET is a unique secret used to secure authentication tokens. Umami 3.5 requires an explicit value before startup. Generate it before deployment and retain it in your private recovery records.
Can a website on shared hosting use my Umami VPS?
Yes. Run the analytics application on the VPS and add its generated tracking script to your website through the supported theme, template or integration method. Website visitors need access to the tracker and collection endpoint.
How do I enable Umami browser error tracking?
With Umami 3.5, add data-errors="true" to the website tracking script. Review captured JavaScript exceptions and unhandled promise rejections in that website's Errors tab.
What should I back up for self-hosted Umami?
Back up PostgreSQL and retain the Compose file, private environment settings, application secret, two-factor encryption key and proxy configuration. Keep encrypted recovery copies away from the live server and test a restore.

