Installation

There are several different ways to install Umami.

• Installing from source: Get the code from GitHub and build the application yourself.
• Using Docker Compose: Build your own Docker container using docker compose.
• Using a Docker image: Download a pre-built Docker image.
• Using Kubernetes with HelmForge: Deploy Umami with a third-party Helm chart maintained by the HelmForge project. See the Running on Kubernetes with HelmForge guide.

Installing from source#

Requirements#

• A server with Node.js version 20.19 or newer (22 LTS recommended).
• A database. Umami supports PostgreSQL (minimum v12.14) databases.

Install pnpm#

npm install -g pnpm

Get the source code and install packages#

git clone https://github.com/umami-software/umami.git
cd umami
pnpm install

Configure Umami#

Create an .env file with the following:

DATABASE_URL={connection url}
APP_SECRET={random string}

The connection URL is in the following format:

DATABASE_URL=postgresql://username:mypassword@localhost:5432/mydb

APP_SECRET is required and secures authentication tokens. Generate one with openssl rand -hex 32. See APP_SECRET.

Build the application#

pnpm build

The first time the build is run, it will create all the required database tables in your database. It will also create a login account with username admin and password umami. You will be asked to change this password the first time you log in.

Start the application#

pnpm start

By default this will launch the application on http://localhost:3000. You will need to either proxy requests from your web server or change the port to serve the application directly.

To bind to the HOSTNAME and PORT set in your .env file, start with pnpm run start:env instead.

Running Umami#

You can simply run pnpm start to start Umami, but it's highly recommended you use a process manager like PM2 which will handle restarts for you.

To run with PM2:

pnpm add -g pm2
cd umami
pm2 start "pnpm start" --name umami
pm2 startup
pm2 save

Installing with Docker#

Umami ships with a Docker Compose file that contains the application and a PostgreSQL database.

The Compose file reads APP_SECRET from an .env file next to it and will not start without it. Create the file first:

APP_SECRET={random string}

Generate the value with openssl rand -hex 32.

To build the Docker container and start up with a PostgreSQL database, run:

docker compose up -d

This will create a PostgreSQL database and start the Umami application on http://localhost:3000. The default login credentials are username admin and password umami. You will be asked to change this password the first time you log in.

Alternatively, if you want to use prebuilt images, you can pull the Umami Docker image:

docker pull docker.umami.is/umami-software/umami:latest

When using a prebuilt image, you need to provide your own database and set the DATABASE_URL and APP_SECRET environment variables. See Environment variables for configuration options.