Deploying an Umami App

Introduction

Umami is a privacy-focused web analytics platform that runs on Node.js with a PostgreSQL backend. This guide walks through containerizing Umami, configuring secrets, connecting to Postgres, and deploying to Klutch.sh over HTTP.

Prerequisites

• GitHub repository containing your Dockerfile.
• PostgreSQL database (managed or deployed separately).
• Klutch.sh project ready in klutch.sh/app.

Project structure

.
└── Dockerfile

Sample Dockerfile

FROM ghcr.io/umami-software/umami:postgresql-latest

# Default Umami port
ENV PORT=3000
EXPOSE 3000

Required environment variables

• DATABASE_URL – e.g., postgres://USER:PASSWORD@HOST:PORT/DB
• APP_SECRET – strong random string for signing
• PORT – internal port (default 3000)

Optional environment variables

• TRACKER_SCRIPT_NAME – customize tracker path (default umami.js)
• HASH_SALT – add salt for hashed IPs
• NODE_ENV=production

Persistence

All data lives in PostgreSQL. No local volume is required unless you extend Umami to store files.

Networking

• Protocol: HTTP
• Internal port: 3000
• Users reach https://example-app.klutch.sh while Klutch.sh routes to port 3000 inside the container.

Health check (recommended)

curl -I http://localhost:3000

Deployment on Klutch.sh

1. Push your Dockerfile to GitHub.
2. In klutch.sh/app, create a new app and select GitHub as the source.
3. Klutch.sh automatically detects the Dockerfile in the repository root.
4. Select HTTP traffic and set the internal port to 3000.
5. Add environment variables for DATABASE_URL, APP_SECRET, and any tracker customization. Mark secrets as sensitive.
6. Deploy. After first boot, create your admin user in the Umami UI.

Verification

• UI: open https://example-app.klutch.sh and confirm the login page appears.

• Quick check:

  curl -I https://example-app.klutch.sh

Next steps

• Add your domains and tracking script to your sites.
• Set up database backups for PostgreSQL.
• Rotate APP_SECRET periodically and maintain strong database credentials.