Deploying with Podman
Relevant source files
The following files were used as context for generating this wiki page:
This document outlines the process for deploying the Umami application using Podman and podman-compose. This method provides a containerized environment for both the Umami application and its PostgreSQL database, ensuring a consistent and isolated setup. The provided configuration is designed for ease of use and has been tested on Debian GNU/Linux 12 with Podman v4.3+.
Sources: podman/README.md, README.md:39-49
Architecture
The Podman deployment consists of two main services defined in the podman-compose.yml file: umami and db.
umami: The main application service, which runs the Umami Next.js application. It is built from the local Dockerfile.db: The PostgreSQL database service, which is required by the Umami application for data storage.
The following diagram illustrates the service architecture.
Sources: podman/podman-compose.yml:3-23
Service Details
The table below details the configuration of each service in the podman-compose.yml file.
| Service | Image | Ports | Depends On | Environment Variables | Command |
|---|---|---|---|---|---|
umami | localhost/umami-software/umami:postgresql-latest | 3000:3000 | db | DATABASE_URL, APP_SECRET | pnpm start-docker |
db | docker.io/postgres:15-alpine | 5432:5432 | - | POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD | - |
Sources: podman/podman-compose.yml:3-23
Configuration
Configuration is managed through an .env file located in the podman directory. You must rename the provided env.sample to .env and populate it with your desired values. At a minimum, passwords must be set.
Sources: podman/README.md:5-7
Environment Variables
These variables are defined in podman-compose.yml and should be set in your .env file.
| Variable | Service | Description | Example |
|---|---|---|---|
DATABASE_URL | umami | The connection URL for the PostgreSQL database. | postgresql://umami:password@db:5432/umami |
APP_SECRET | umami | A secret key used for signing security tokens. | generate a random string |
POSTGRES_DB | db | The name of the database to be created. | umami |
POSTGRES_USER | db | The username for the database. | umami |
POSTGRES_PASSWORD | db | The password for the database user. | your_secure_password |
Sources: podman/podman-compose.yml:10-11, 20-22, podman/README.md:6
Deployment Process
The deployment process is initiated using podman-compose. The following flowchart outlines the required steps.
Sources: podman/README.md:5-10
Container Startup Sequence
When the umami service starts, it executes the pnpm start-docker command. This command is an alias for a sequence of npm scripts defined in package.json.
The following sequence diagram shows the startup process within the umami container.
The check-db.js script performs several critical functions:
- Environment Check: Verifies that
DATABASE_URLis defined. - Connection Check: Attempts to connect to the database using the Prisma client.
- Version Check: Ensures the PostgreSQL version is at least
9.4.0. - Migration: Applies any pending database migrations using
prisma migrate deploy, unlessSKIP_DB_MIGRATIONis set.
Sources: scripts/check-db.js:10, 31-69
Optional: Install as a systemd Service
For long-running deployments, you can install a systemd service to manage the Umami application. The repository provides a template umami.service file.
Setup Steps
- Edit
umami.service:- Set
WorkingDirectoryto the absolute path wherepodman-compose.ymlis located. - Set
EnvironmentFileto the absolute path of your.envfile.
- Set
- Run Installer: Execute the
./install-systemd-user-servicescript. This will install, enable, and start the service for the current user.
Note: Before running the installer, ensure Umami is not already running by executing podman-compose down.
The following diagram shows the systemd installation flow.
Sources: podman/README.md:13-32
Summary
Deploying Umami with Podman offers a containerized, reproducible, and isolated environment that simplifies dependency management. By using the provided podman-compose.yml and .env configuration, users can quickly launch the application and its database. The optional systemd integration further enhances manageability for production-like environments, ensuring the application runs reliably as a background service.
Sources: podman/README.md, podman/podman-compose.yml