Development Environment Setup

Relevant source files

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

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

# Development Environment Setup

This document provides a comprehensive guide to setting up a local development environment for the Umami application. Umami is a simple, fast, privacy-focused alternative to Google Analytics. This guide covers two primary setup methods: installing from the source code and using Docker. It details the necessary prerequisites, configuration, and key scripts required for building, running, and testing the application.

The setup process involves cloning the repository, installing dependencies, configuring the database connection, and running build and start scripts. Developers can choose the method that best fits their workflow, with Docker providing a more encapsulated environment and source installation offering more direct control.

Prerequisites

Before beginning the installation, ensure your development environment meets the following requirements:

• Node.js: Version 18.18 or higher.
• PostgreSQL: Version 12.14 or higher.

Sources: README.md:18-20

Installation from Source

This method involves manually setting up the application by cloning the source code, installing dependencies, and running build scripts.

Setup Flow

The following diagram illustrates the high-level steps for installing and running the application from the source code.

Sources: README.md:23-43

Step-by-Step Guide

1. Get the source code and install packages:
   Clone the repository and install the required pnpm packages.

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

   Sources: README.md:24-26

2. Configure Umami:
   Create a .env file in the root of the project and add your PostgreSQL database connection URL.

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

   Sources: README.md:29-35

3. Build the Application:
   The build command compiles the application, including the tracker script and frontend. On the first run, it will also create the necessary tables in your database and a default user with username admin and password umami.

   pnpm run build
   

   The build script is an alias that runs a sequence of other scripts, as defined in package.json.

   "build": "npm-run-all check-env build-db check-db build-tracker build-geo build-app",
   

   Sources: README.md:38-43, package.json:12

4. Start the Application:
   This command starts the Next.js server.

   pnpm run start
   

   By default, the application will be available at http://localhost:3000.
   Sources: README.md:46-48, package.json:13

Docker-Based Setup

For a more streamlined setup, you can use the provided Docker Compose configuration, which orchestrates the Umami application and a PostgreSQL database.

Docker Architecture

The docker-compose.yml file defines two main services: umami and db. The umami service builds from the local Dockerfile and depends on the db service.

Sources: docker-compose.yml

Running with Docker

To start both the application and the database, run the following command from the project root:

docker compose up -d

Sources: README.md:57-59

The umami service in the docker-compose.yml file is configured with the necessary environment variables and port mappings.

services:
  umami:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - '3000:3000'
    environment:
      DATABASE_URL: postgresql://umami:umami@db:5432/umami
      DATABASE_TYPE: postgresql
      APP_SECRET: ${APP_SECRET:-umami}
    depends_on:
      - db
    restart: always
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: umami
    volumes:
      - ./sql/schema.postgresql.sql:/docker-entrypoint-initdb.d/schema.postgresql.sql
      - ./umami-db-data:/var/lib/postgresql/data
    restart: always

Sources: docker-compose.yml:3-29

To update your Docker-based instance, pull the latest images and recreate the containers:

docker compose pull
docker compose up --force-recreate -d

Sources: README.md:66-69

Core Scripts

The package.json file contains several scripts for common development tasks.

Script	Description
dev	Starts the Next.js development server with Turbo, running on port 3001.
build	Executes a sequence of tasks: check-env, build-db, check-db, build-tracker, build-geo, and build-app.
start	Starts the production Next.js server.
check-db	Runs a script to verify the database connection, version, and apply migrations.
update-db	Applies pending database migrations using prisma migrate deploy.
seed-data	Populates the database with sample data for testing.
lint	Lints the codebase using Biome.
format	Formats the codebase using Biome.
cypress-run	Executes Cypress end-to-end tests.

Sources: package.json:11-39

Database Management

Database setup and maintenance are handled by Prisma and a set of helper scripts.

Database Checks (check-db)

The pnpm run check-db command executes scripts/check-db.js, which performs a series of validations to ensure the database is ready.

Sources: scripts/check-db.js:10-72

The script will exit with an error if any of the checks fail, preventing the application from starting with a misconfigured database.

Seeding Test Data

The project includes a script to generate realistic sample data for development and testing.

# Generate 30 days of data (default)
pnpm run seed-data

# Generate 90 days of data
pnpm run seed-data -- --days 90

# Clear existing demo data before generating
pnpm run seed-data -- --clear

This script is blocked from running in production environments. It creates two demo websites: "Demo Blog" (low traffic) and "Demo SaaS" (average traffic).

Sources: scripts/seed-data.ts:10-16, scripts/seed-data.ts:80-82, package.json:38

Configuration

The application is configured primarily through environment variables.

Environment Variables

These variables are referenced in next.config.ts and other parts of the application.

Variable	Description	Default	Source File
DATABASE_URL	The connection string for the PostgreSQL database.	-	README.md:32
BASE_PATH	A path prefix for the application URL.	''	next.config.ts:6
TRACKER_SCRIPT_NAME	A comma-separated list of alternative names for the tracker script.	''	next.config.ts:12
FORCE_SSL	If set, enables the Strict-Transport-Security header.	''	next.config.ts:9
DISABLE_UI	If set, the application will render an empty HTML body.	-	src/app/layout.tsx:11

Sources: README.md:32, next.config.ts:6-12, src/app/layout.tsx:11-16

Code Formatting and Linting

The project uses Biome for code formatting and linting. The configuration is defined in biome.json.

{
  "formatter": {
    "enabled": true,
    "lineWidth": 100,
    "indentStyle": "space",
    "indentWidth": 2
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  }
}

You can run the linter and formatter with pnpm run lint and pnpm run format.

Sources: biome.json:8-20, package.json:39-41

Conclusion

Setting up a development environment for Umami can be accomplished either by a manual installation from source or a more automated process using Docker. Both methods require a PostgreSQL database and Node.js. The repository is well-equipped with scripts for building, testing, linting, and managing the application, ensuring a consistent and efficient development workflow. Following the steps in this guide will result in a fully functional local instance of Umami, ready for development and testing.