Get Umbrella running
in three minutes.

Prerequisites

You need exactly one of:

• Docker 24+ on any Linux/macOS machine, OR
• A Coolify v4 instance with a public IP, OR
• Python 3.11+ if you’re going bare metal.

For production, also have a domain name pointed at the host.

Docker

The fastest way. Clone the repo — the included docker-compose.yml already builds Umbrella from the bundled Dockerfile.

services:
  umbrella:
    build:
      context: .
      dockerfile: docker/Dockerfile
    restart: unless-stopped
    ports: ["8080:8080"]
    environment:
      UMBRELLA_SECRET_KEY:    "${UMBRELLA_SECRET_KEY}"
      UMBRELLA_COOKIE_SECURE: "false"
      UMBRELLA_DATABASE_URL:  "sqlite+aiosqlite:////app/data/umbrella.db"
    volumes:
      - umbrella-data:/app/data

volumes:
  umbrella-data:

Boot it

# 1. clone the repo
git clone https://github.com/aeon-pro/Umbrella.git
cd Umbrella

# 2. generate a secret
export UMBRELLA_SECRET_KEY="$(openssl rand -base64 48)"

# 3. build & up
docker compose up --build -d

# 3. open the dashboard, finish first-run setup
open http://localhost:8080/dashboard

That’s it. The named volume umbrella-data persists the SQLite DB and request logs across restarts. You don’t need to do anything else.

Coolify

The recommended path for hands-off production.

• New Resource → Application → Public Repository → paste the URL.
• Build Pack: Docker Compose (this matters — not Dockerfile).
• Domain: https://umbrella.example.com — Coolify auto-issues Let’s Encrypt.
• Environment Variables:
  • UMBRELLA_SECRET_KEY = output of openssl rand -base64 48
  • UMBRELLA_COOKIE_SECURE = true
• Click Deploy. The named volume gets created automatically — no manual storage config.

When you push new code to GitHub, Coolify auto-redeploys and the volume is preserved — you don’t lose the admin or any config.

Manual / venv

For local development or if you really don’t want Docker:

git clone https://github.com/aeon-pro/Umbrella.git
cd Umbrella

python3.11 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

cp .env.example .env
# edit UMBRELLA_SECRET_KEY at minimum

uvicorn app.main:app --host 0.0.0.0 --port 8080 --proxy-headers

First-run setup

The first time you open /dashboard, you’ll see a bootstrap form instead of a login. Whatever username and password you enter becomes the admin account.

To skip the UI and pre-create the admin from env vars:

UMBRELLA_BOOTSTRAP_ADMIN_USERNAME=admin
UMBRELLA_BOOTSTRAP_ADMIN_PASSWORD=your-strong-password

The admin is created on first start if no users exist; otherwise these vars are ignored.

Environment variables

Every setting comes from an UMBRELLA_* env var. The most useful ones:

Persistence

The Dockerfile declares VOLUME ["/app/data"] so any container runtime auto-creates a persistent volume there. The SQLite DB, request log, and audit log all survive container restarts and redeploys.

For host-side persistence with a friendly name (so backups are easy), build the image once and mount your own volume:

# build once from the cloned repo
docker build -t umbrella:local -f docker/Dockerfile .

# run with a named volume mounted on /app/data
docker run -d -p 8080:8080 \
  -v umbrella-data:/app/data \
  -e UMBRELLA_SECRET_KEY="$(openssl rand -base64 48)" \
  umbrella:local

TLS & reverse proxies

Umbrella expects to be the only thing on its port. Put your TLS terminator (Caddy, nginx, Traefik, Cloudflare) in front and forward to it. Set UMBRELLA_FORWARDED_ALLOW_IPS=* so client IPs are honored from X-Forwarded-For.

Caddyfile

api.example.com {
    reverse_proxy umbrella:8080
}

Cloudflare in front

If your origin already has a real Let’s Encrypt cert (Coolify does this automatically), set Cloudflare’s SSL/TLS mode to Full (strict). Anything else and you’ll see weird errors.

ClickHouse analytics

By default, request logs go into the SQL database (SQLite/Postgres) and the dashboard’s Analytics page reads from there. Fine for dev and low traffic.

For high-volume production, set one env var:

UMBRELLA_CLICKHOUSE_URL=http://default:password@clickhouse:8123/umbrella

Umbrella creates the schema on first start, batches inserts, and runs aggregate queries directly on ClickHouse. The dashboard’s Analytics page shows a small clickhouse chip so you know it’s active.

See the docs for the full setup including TTL, schema, and tuning.