Skip to content

Self-hosting quick start

Run your own OpenWatch in a few minutes with a container runtime. The whole stack is containerised, so you do not need a local Python environment. Podman is the recommended runtime; Docker works the same way.

Prerequisites

  • Podman with podman-compose (recommended), or Docker with Compose.
  • Git.
  • A few minutes and an OpenStack project to connect afterwards.

1. Get the code

git clone <repo-url>
cd openwatch

2. Create your environment file

cp .env.example .env

3. Generate the two required secrets

OpenWatch needs a SECRET_KEY (Flask sessions and CSRF) and a MASTER_KEY (encryption of stored credentials).

# SECRET_KEY - a 64-character hex string
python3 -c "import secrets; print(secrets.token_hex(32))"

# MASTER_KEY - a base64 Fernet key
python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Paste both values into .env:

SECRET_KEY=<your_secret_key_here>
MASTER_KEY=<your_master_key_here>

Keep MASTER_KEY safe

If you lose MASTER_KEY, every value encrypted with it (OpenStack passwords, SMTP passwords, OAuth and OIDC secrets, and more) becomes permanently unreadable. Back it up somewhere secure. There is no recovery path.

The Flower monitoring dashboard also requires a password. Set FLOWER_PASSWORD in .env or the stack will refuse to start the Flower service. See Configuration for the full list of variables.

4. Start the stack

podman-compose up -d --build

docker compose up -d --build

This brings up all services: the database, Redis, the main app, the admin console, the Celery worker and beat scheduler, and Flower.

Service Port Purpose
Main app 8000 End-user dashboard, org admin, billing
Admin console 8001 Site-wide super-admin
Flower 5555 Celery task monitoring

Database migrations run automatically on start, so the schema is always up to date before the app serves traffic.

5. First-run setup

  1. Open http://localhost:8000.
  2. On first launch, with no users yet, OpenWatch shows an automatic setup page. Create the first account; it becomes the super-admin.
  3. Log in, then go to Administration and add your first OpenStack project. See Connect your cloud for the exact fields.
  4. Return to the dashboard to see your costs. The first data load runs in the background, so the page may briefly show a refreshing state.

Behind a reverse proxy

In production, terminate TLS at a reverse proxy and set TALISMAN_FORCE_HTTPS=true. See Configuration.

Useful commands

# Follow the app logs
podman-compose logs -f app

# Stop the stack
podman-compose down

# Rebuild after pulling new code
podman-compose up -d --build

docker compose logs -f app
docker compose down
docker compose up -d --build

Deleting data

Adding -v to the down command (podman-compose down -v or docker compose down -v) also deletes the PostgreSQL volume and all stored data. Use it only when you really want a clean slate.