> ## Documentation Index
> Fetch the complete documentation index at: https://help.freakhosting.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Self-Host Umami Analytics with Docker

> Self-host Umami analytics with Docker Compose: run the Umami and PostgreSQL containers, serve them over HTTPS, log in as admin/umami and add your tracking code.

To self-host Umami analytics, create the official `compose.yaml` with the `ghcr.io/umami-software/umami:latest` and `postgres:15-alpine` images, set a random `APP_SECRET` and database password, and run `sudo docker compose up -d`. Serve port 3000 through Nginx with HTTPS, log in with `admin` / `umami`, change the password and add your website.

| Difficulty | Time | Works on | Needs |
| - | - | - | - |
| Beginner | 20 minutes | Ubuntu 22.04 / 24.04, Debian 12 / 13, AlmaLinux / Rocky 9 / 10 | [Docker](https://help.freakhosting.com/portals/other/how-to-install-docker.md), a domain, HTTPS |

## What is Umami?

Umami is an open-source, privacy-focused web analytics tool, a self-hosted alternative to Google Analytics. A small script on your site records page views and events in your own PostgreSQL database, and Umami shows them on a dashboard.

## Before you start

* [Install Docker](https://help.freakhosting.com/portals/other/how-to-install-docker.md) and [Nginx](https://help.freakhosting.com/portals/other/how-to-install-nginx.md). The commands use `sudo`; leave it out if you are `root`.
* Point a subdomain such as `stats.example.com` at your server. See [point a domain to your server](https://help.freakhosting.com/portals/other/how-to-point-a-domain-to-your-server.md).
* Use HTTPS. Browsers block a tracking script loaded over HTTP from an HTTPS website.

## How to install Umami with Docker Compose

**1. Create a folder and secrets**

```bash theme={null}
mkdir -p ~/umami && cd ~/umami
printf 'DB_PASSWORD=%s\nAPP_SECRET=%s\nTWO_FACTOR_ENCRYPTION_KEY=%s\n' \
  "$(openssl rand -hex 16)" "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
chmod 600 .env
```

`APP_SECRET` secures login tokens and must be unique per installation. `TWO_FACTOR_ENCRYPTION_KEY` (64 hex characters) is needed before anyone can turn on two-factor authentication.

**2. Create compose.yaml**

This is the [official Umami compose file](https://github.com/umami-software/umami/blob/master/docker-compose.yml) with the secrets moved to `.env` and the port bound to `127.0.0.1`:

```yaml theme={null}
services:
  umami:
    image: ghcr.io/umami-software/umami:latest
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:${DB_PASSWORD}@db:5432/umami
      APP_SECRET: ${APP_SECRET}
      TWO_FACTOR_ENCRYPTION_KEY: ${TWO_FACTOR_ENCRYPTION_KEY}
    depends_on:
      db:
        condition: service_healthy
    init: true
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
      interval: 5s
      timeout: 5s
      retries: 5
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5
volumes:
  umami-db-data:
```

`DATABASE_URL` is the only setting Umami requires. The database is reachable only on the internal Compose network.

**3. Start Umami**

```bash theme={null}
sudo docker compose up -d
```

On first start Umami creates its database tables and the default admin user.

## How to serve Umami over HTTPS with Nginx

**1. Create the Nginx site**

Create `/etc/nginx/sites-available/stats.example.com` (Ubuntu / Debian) or `/etc/nginx/conf.d/stats.example.com.conf` (AlmaLinux / Rocky):

```nginx theme={null}
server {
    listen 80;
    listen [::]:80;
    server_name stats.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

**2. Enable, test and get a certificate**

```bash theme={null}
sudo ln -s /etc/nginx/sites-available/stats.example.com /etc/nginx/sites-enabled/   # Ubuntu / Debian only
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d stats.example.com
```

On AlmaLinux / Rocky, run `sudo setsebool -P httpd_can_network_connect 1` before testing.

## How to log in and add your website

**1. Log in and change the password**

Open `https://stats.example.com` and log in with username `admin` and password `umami`. Change the password at once: open the profile button in the side navigation, select **Settings**, go to **Profile** and click **Change password**.

**2. Add a website**

Click **Websites** in the sidebar, then **Add website**. Enter a **Name** and the site's **Domain**, for example `example.com`, and click **Save**.

**3. Install the tracking code**

Click **Edit** on the website, copy the code from the **Tracking code** section and paste it into the `<head>` of every page of your site.

> [!WARNING]
>
> Until you change it, anyone who finds your Umami address can log in with the published default password `admin` / `umami`. Change it before you share the address or add the tracking code.

## How to check it worked

```bash theme={null}
sudo docker compose ps
curl -s http://127.0.0.1:3000/api/heartbeat
```

Both containers show `Up (healthy)`, and the heartbeat request returns a response. Open your website in another browser tab, then open the website in Umami: the visit appears on its dashboard.

## How to back up Umami

All analytics data is in PostgreSQL. Dump it to a file:

```bash theme={null}
cd ~/umami
sudo docker compose exec -T db pg_dump -U umami umami > umami-$(date +%F).sql
```

Copy the dump and your `.env` off the server. See [back up Docker volumes](https://help.freakhosting.com/portals/other/how-to-back-up-docker-volumes.md) and [back up to cloud storage with rclone](https://help.freakhosting.com/portals/other/how-to-back-up-to-cloud-storage-with-rclone.md).

## How to update Umami

Back up first, then:

```bash theme={null}
cd ~/umami
sudo docker compose pull
sudo docker compose up --force-recreate -d
```

Major upgrades, such as moving to v3, run database migrations. If dashboards are slow afterwards on a large install, the Umami docs suggest running `ANALYZE;` on the database:

```bash theme={null}
sudo docker compose exec db psql -U umami -d umami -c "ANALYZE;"
```

## Frequently asked questions

### What is the default Umami login?

Username `admin`, password `umami`. Umami creates this user when it first sets up the database.

### Why are visits not recorded?

Ad blockers often block `script.js`. Set `TRACKER_SCRIPT_NAME` to a different name in the Umami environment, recreate the container and copy the new tracking code. Also check that the website's **Domain** in Umami matches your site.

### Can I track several websites with one Umami?

Yes. Add each site under **Websites > Add website**. Each website has its own tracking code under **Edit > Tracking code**.

### How do I turn off Umami's telemetry?

Add `DISABLE_TELEMETRY: 1` to the `umami` service's `environment` and run `sudo docker compose up -d`.

## Related guides

> [card] [VPS and dedicated server guides](https://help.freakhosting.com/portals/other/vps-and-dedicated-server-guides.md)
>
> Every guide in this section.

> [card] [Docker Compose tutorial](https://help.freakhosting.com/portals/other/how-to-use-docker-compose.md)
>
> How compose.yaml works.

> [card] [Nginx reverse proxy](https://help.freakhosting.com/portals/other/how-to-set-up-nginx-as-a-reverse-proxy.md)
>
> Serve containers on your domain.

> [card] [Free SSL with Certbot](https://help.freakhosting.com/portals/other/how-to-get-a-free-ssl-certificate-with-certbot.md)
>
> HTTPS for your analytics domain.

> [card] [Update Docker containers](https://help.freakhosting.com/portals/other/how-to-update-docker-containers.md)
>
> Pull new images safely.

***

> [!NOTE]
>
> **Checked against the official [Umami documentation](https://docs.umami.is/docs/install) and [compose file](https://github.com/umami-software/umami/blob/master/docker-compose.yml)** on 4 November 2026 (images `ghcr.io/umami-software/umami:latest` and `postgres:15-alpine`); `compose.yaml` validated with `docker compose config` and the Nginx configuration syntax-tested on Ubuntu 24.04 LTS. Menu names can change between Umami releases.

> [!NOTE]
>
> ### Need Extra Help?
>
> If you encounter any issues, our support team is ready to assist:
>
> * **Live Chat:** Quick assistance via our website.
> * **Support Ticket:** [Open a Ticket](https://freakhosting.com/clientarea/submitticket.php)
> * **Discord:** [Join our Community](https://discord.gg/freakhosting)
> * **Email:** [support@freakhosting.com](mailto:support@freakhosting.com)

> [!TIP]
>
> ### Save on Your Hosting
>
> Ready to upgrade your hosting? Use code **KB20** at checkout for **20% off** your first order!

***

**Last Updated:** November 2026


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.