Add default docker image with BASE_PATH=/stats

Context

BASE_PATH is a build-time variable in Umami, meaning it must be baked into the Docker image at build time. The official pre-built image on ghcr.io does not include any BASE_PATH, making it impossible to deploy Umami under a subpath without maintaining a custom image.

Proposal

Adapt the CI/CD pipeline to automatically publish an additional Docker image variant built with BASE_PATH=/stats, alongside the default image.

For example, the following tags could be published on each release:

Tag	Description
`ghcr.io/umami-software/umami:postgresql-latest`	Current default image
`ghcr.io/umami-software/umami:postgresql-latest-stats`	New image built with `BASE_PATH=/stats`

Why

This is a common self-hosting use case — many users deploy multiple apps under subpaths on a single domain (e.g. /stats, /analytics) behind a reverse proxy. Without a pre-built image variant, they are forced to maintain their own custom image and rebuild it on every Umami release, which is not sustainable.

Alternative considered

Exposing BASE_PATH as a runtime environment variable would be the ideal long-term solution, but requires changes to the Next.js build pipeline. The CI/CD approach proposed here is a lower-effort improvement that would immediately benefit self-hosted users.

Theres a PR out for this. I'll review it today.

That's great ! Thank you so much 👍

Merge pull request #3991 from Yashh56/fix/base_path. Closes #4064

Its approved, but its currently hardcoded to /umami as the default, not /stats. Of course you can update the workflow file to choose any base path needed.

I think it should set it to a non-'umami' string; otherwise, it'll be easily blocked by AdBlock rules.

If you have a CI/CD pipeline, just build your own image. We should not build extra images. Having one for /stats, /umami, /analytics, /whatever is not sustainable.

If you have a CI/CD pipeline, just build your own image. We should not build extra images. Having one for /stats, /umami, /analytics, /whatever is not sustainable.

We don't have any CI/CD pipelines, so we need an official image.

In my usecase, the /umami would work great.
I just need to be able to deploy the app on the same hostname as my website, because I'm limited by my VPS provider.

In my usecase, the /umami would work great. I just need to be able to deploy the app on the same hostname as my website, because I'm limited by my VPS provider.

However, it seems like the owners are reluctant to build official images.

While waiting for a better solution, for those with the same issue, here's how to build a new docker image and push it to your Github project :

# Download official umami repo : 
git clone https://github.com/umami-software/umami.git
cd umami

# Here replace with your variables : 
USERNAME="<my github username>"
REPO="<my github project>"
SUB_BASE_PATH="<my base_path (ex: stats for /stats)>"
CR_PAT="<my github deploy token>" # see https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens to generate token

# Login to github with docker, in order to push the new image
echo $CR_PAT | docker login ghcr.io -u ${USERNAME} --password-stdin 

# Build and push the image, making sure to have compatibility with different platforms : 
docker buildx build --platform linux/amd64,linux/arm64 --build-arg BASE_PATH=/${SUB_BASE_PATH} -t ghcr.io/${USERNAME}/${REPO}/umami:path-${SUB_BASE_PATH} --push .

While waiting for a better solution, for those with the same issue, here's how to build a new docker image and push it to your Github project :

Could you write a tutorial on how to use GitHub Actions to check out source code from the source repo, then compile and publish it to GHCR? I remember this is possible, but I don't know how to do it.

Here is the answer according to claude.ai.
I'll have to wait to merge my dev branch into main in order to check if it actually works.

# .github/workflows/build-umami.yml
name: Build and push Umami image

on:
  workflow_dispatch:  # Déclenchement manuel
    inputs:
      base_path:
        description: 'Base path (ex: stats for /stats)'
        required: true
        default: 'stats'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout umami source
        uses: actions/checkout@v4
        with:
          repository: umami-software/umami
          ref: master

      - name: Log in to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}  # Automatique, pas besoin de créer un secret

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          build-args: |
            BASE_PATH=/${{ github.event.inputs.base_path }}
          tags: |
            ghcr.io/${{ github.repository }}/umami:path-${{ github.event.inputs.base_path }}
            ghcr.io/${{ github.repository }}/umami:latest

Navigation Menu

Repository navigation

Add default docker image with BASE_PATH=/stats #4064

Context

Proposal

Why

Alternative considered

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Add default docker image with BASE_PATH=/stats #4064

Description

Context

Proposal

Why

Alternative considered

Activity

franciscao633 commented on Mar 4, 2026

Matthiosso commented on Mar 4, 2026

franciscao633 commented on Mar 5, 2026

E021ntox commented on Mar 5, 2026

mikecao commented on Mar 5, 2026

E021ntox commented on Mar 5, 2026

Matthiosso commented on Mar 5, 2026

E021ntox commented on Mar 5, 2026

Matthiosso commented on Mar 8, 2026

E021ntox commented on Mar 8, 2026

Matthiosso commented on Mar 8, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions