Deploying with Docker

Relevant source files

The following files were used as context for generating this wiki page:

• docker-compose.yml
• README.md
• package.json
• podman/README.md
• scripts/check-db.js
• next.config.ts

Umami provides a streamlined deployment process using Docker and Docker Compose, encapsulating the application and its database dependency into manageable containers. This approach simplifies setup, configuration, and updates by providing a consistent environment for running the Umami analytics platform.

The primary method involves using a docker-compose.yml file which orchestrates the Umami application container and a PostgreSQL database container. Pre-built Docker images are also available for direct use. An alternative deployment using Podman is also supported for users who prefer it over Docker.

Sources: README.md:38-47, podman/README.md

Docker Compose Architecture

The docker-compose.yml file defines a multi-container setup consisting of two main services: umami and db. This architecture ensures that the application and its database are networked together and can be managed as a single unit.

Sources: docker-compose.yml

The following diagram illustrates the relationship between the services defined in the docker-compose.yml file.

Services

The table below details the services configured in the docker-compose.yml file.

Service	Image	Build Context	Ports	Depends On	Environment	Volumes
umami	-	. (builds from source)	3000:3000	db	Loaded from .env file	-
db	postgres:15-alpine	-	-	-	Loaded from .env file	umami-db-data:/var/lib/postgresql/data

Sources: docker-compose.yml:3-20

Configuration

Both services are configured using an environment file. The umami service relies on the db service, which must be running before the application starts. The db service uses a named volume umami-db-data to persist PostgreSQL data across container restarts.

# docker-compose.yml
services:
  umami:
    build: .
    ports:
      - '3000:3000'
    env_file: .env
    depends_on:
      - db
  db:
    image: postgres:15-alpine
    env_file: .env
    volumes:
      - umami-db-data:/var/lib/postgresql/data

Sources: docker-compose.yml:3-20

Deployment and Startup

Using Docker Compose

The primary method for deploying Umami with Docker is by using the provided docker-compose.yml file. This single command will download the necessary images, build the Umami container, and start both the application and database services in detached mode.

Command:

docker compose up -d

Sources: README.md:46-47

The startup process initiated by docker compose up involves several steps within the umami container, managed by npm scripts.

This sequence diagram shows the high-level interaction when a user starts the application.

Using Podman

For users in a Podman environment, a podman-compose.yml is provided. The process is similar to Docker Compose.

1. Rename env.sample to .env and edit it with your database passwords.
2. Run podman-compose up -d to start the services.

A systemd service file, umami.service, is also available for automatically running Umami on system startup.

Sources: podman/README.md:6-10, podman/README.md:16-22

Container Scripts

The package.json file defines specific scripts for building and starting the application within a Docker environment. These are executed automatically during the docker compose lifecycle.

Sources: package.json:9-11

Build Process (build-docker)

When the umami service is built for the first time, the build-docker script is executed. This script orchestrates several sub-tasks to prepare the application.

// package.json:9
"build-docker": "npm-run-all build-db build-tracker build-geo build-app",

The following flowchart illustrates the steps in the build-docker script.

Startup Process (start-docker)

On container startup, the start-docker command is run. This script ensures the database is ready and then starts the application server.

// package.json:10
"start-docker": "npm-run-all check-db update-tracker start-server",

The check-db script is a critical first step. It performs the following actions:

1. Checks if DATABASE_URL is defined.
2. Attempts to connect to the database.
3. Verifies the PostgreSQL version is compatible (>= 9.4.0).
4. Applies any pending database migrations using prisma migrate deploy.

Sources: scripts/check-db.js:12-58

This flowchart shows the sequence of the start-docker script.

Updating the Deployment

To update an existing Docker-based deployment to the latest version of Umami, you need to pull the newest image and recreate the container.

The following commands should be run in the directory containing your docker-compose.yml file:

1. Pull the latest images: This fetches the latest postgres and umami images.

   docker compose pull
   

2. Recreate and start the services: This stops the old containers and starts new ones using the updated images, while preserving the database volume. The --force-recreate flag ensures new containers are created.

   docker compose up --force-recreate -d
   

Sources: README.md:53-57

Summary

Deploying Umami with Docker provides a robust and isolated environment by leveraging Docker Compose to manage the application and its PostgreSQL database. The process is automated through scripts defined in package.json for building the application and ensuring the database is correctly migrated on startup. Updates are handled gracefully with standard docker compose commands, making it the recommended method for a self-hosted installation.