Installation

Prerequisites

Hardware

Resource	Minimum	Recommended
RAM	4 GB	8 GB
CPU	2 cores	4 cores
Disk	20 GB	50 GB

Software

Linux host: RHEL 8/9, Rocky Linux, AlmaLinux, Ubuntu 22.04+, or any Docker-capable system
Docker 24+ or Podman 4+ (for container deployment)
Network access to target hosts on port 22 (SSH)
curl and openssl available on the host

Network ports

Port	Service	Direction
3000	Frontend (dev/Docker)	Inbound
8000	Backend API	Inbound
22	SSH to scan targets	Outbound
443/80	Frontend (production)	Inbound

Deployment options

Docker (recommended)
Podman
RPM (bare metal)
From source

Docker Compose is the fastest path to a running OpenWatch instance. The compose file defines six services: PostgreSQL 15, Redis 7, the FastAPI backend, a Celery worker, a Celery beat scheduler, and an Nginx-based React frontend.

1. Clone the repository

git clone https://github.com/Hanalyx/openwatch.git
cd openwatch

2. Configure environment

Copy the example environment file and set secure values:

cp .env.example .env

Open .env and set the required variables:

POSTGRES_PASSWORD=<strong-database-password>
REDIS_PASSWORD=<strong-redis-password>
OPENWATCH_SECRET_KEY=<random-64-char-hex>
MASTER_KEY=<random-64-char-hex>
OPENWATCH_ENCRYPTION_KEY=<random-64-char-hex>

Generate random keys with:

openssl rand -hex 32

3. Start services

./start-openwatch.sh --runtime docker --build

Subsequent starts (without code changes) can skip the build:

./start-openwatch.sh --runtime docker

4. Verify

curl -s http://localhost:8000/health | python3 -m json.tool

5. Log in

Field	Value
Username	`admin`
Password	`admin`

Change the default password immediately after first login.

6. Stop services

# Stop containers, preserve data volumes
./stop-openwatch.sh

# Stop containers and delete all data
./stop-openwatch.sh --deep-clean

OpenWatch supports Podman as an alternative container runtime.

1. Install Podman

# RHEL/Rocky/Alma
sudo dnf install -y podman podman-compose

# Ubuntu/Debian
sudo apt install -y podman podman-compose

2. Clone and configure

Follow the same clone and .env setup steps from the Docker tab.

3. Start services

./start-openwatch.sh --runtime podman --build

Podman-specific notes

Rootless mode: If containers cannot bind to privileged ports (80, 443), either run with sudo or configure net.ipv4.ip_unprivileged_port_start=80 in /etc/sysctl.conf.SELinux volume mounts: On SELinux-enforcing hosts, append :Z to volume mounts:

volumes:
  - ./security/certs:/openwatch/security/certs:ro,Z

Podman socket: Enable if required by compose tooling:

systemctl --user enable --now podman.socket

RPM packages are available for RHEL 9 and compatible distributions.

1. Install external dependencies

# PostgreSQL 15
sudo dnf module enable postgresql:15
sudo dnf install -y postgresql-server postgresql-contrib
sudo postgresql-setup --initdb
sudo systemctl enable --now postgresql

# Redis 7
sudo dnf install -y redis
sudo systemctl enable --now redis

2. Install Python 3.12

sudo dnf install -y python3.12 python3.12-pip python3.12-devel

3. Install OpenWatch

sudo rpm -ivh openwatch-<version>.rpm

4. Install Kensa

sudo python3.12 -m pip install kensa
export KENSA_RULES_PATH=/opt/openwatch/kensa-rules

5. Configure database

sudo -u postgres createuser openwatch
sudo -u postgres createdb -O openwatch openwatch

6. Run migrations

cd /opt/openwatch/backend
python3.12 -m alembic upgrade head

7. Start services

sudo systemctl enable --now openwatch-api
sudo systemctl enable --now openwatch-worker
sudo systemctl enable --now openwatch-beat

This method is intended for developers contributing to OpenWatch.

Prerequisites

Python 3.12+, Node.js 20+, PostgreSQL 15, Redis 7.

Backend

git clone https://github.com/Hanalyx/openwatch.git
cd openwatch/backend
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Celery worker (separate terminal)

cd backend
celery -A app.celery_app worker --loglevel=info \
  -Q default,scans,results,maintenance,monitoring,host_monitoring,health_monitoring,compliance_scanning

Frontend

cd frontend
npm ci
npm run dev

Kensa

pip install kensa
export KENSA_RULES_PATH=/path/to/kensa-rules

Production deployment

For production, use the Docker Compose overlay that enables HTTPS, FIPS mode, resource limits, and JSON logging:

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Setting	Development	Production
`OPENWATCH_DEBUG`	`true`	`false`
`OPENWATCH_FIPS_MODE`	`false`	`true`
`OPENWATCH_REQUIRE_HTTPS`	`false`	`true`
`OPENWATCH_SSH_STRICT_MODE`	`false`	`true`
Frontend ports	3000:80	443:443, 80:80
Resource limits	None	Per-service CPU/memory limits
Log driver	Default	JSON file with rotation
Restart policy	`unless-stopped`	`always`

Before deploying to production:

Place TLS certificates in security/certs/ and keys in security/keys/.
Set all environment variables to strong, unique values.
Configure firewall rules to restrict access to ports 8000 and 3000/443.

Post-install checklist

Backend health check passes: curl http://localhost:8000/health
Frontend loads in browser
Default admin password changed
SSH credentials configured for target hosts
TLS certificates in place (production only)
Log rotation configured for /openwatch/logs/
Firewall rules restrict access to exposed ports

Environment variables

Variable	Description	Example
`POSTGRES_PASSWORD`	PostgreSQL password	Random 32+ character string
`REDIS_PASSWORD`	Redis authentication password	Random 32+ character string
`OPENWATCH_SECRET_KEY`	Application secret for session signing	`openssl rand -hex 32`
`MASTER_KEY`	Master encryption key	`openssl rand -hex 32`
`OPENWATCH_ENCRYPTION_KEY`	Data-at-rest encryption key	`openssl rand -hex 32`

Troubleshooting

Backend container fails to start

Check logs for database connection issues:

docker logs openwatch-backend --tail 50
docker exec openwatch-db pg_isready -U openwatch -d openwatch

Frontend returns 502 Bad Gateway

The backend may still be initializing. Wait 30 seconds and retry. Check that the backend container is running: docker ps | grep openwatch-backend.

Celery worker not processing tasks

docker logs openwatch-worker --tail 50
docker exec openwatch-redis redis-cli -a "${REDIS_PASSWORD}" ping

Permission denied on volume mounts (Podman/SELinux)

Add the :Z suffix to volume mounts in the compose file.

Getting started

Guides

Reference

Prerequisites

Deployment options

1. Clone the repository

2. Configure environment

3. Start services

4. Verify

5. Log in

6. Stop services

1. Install Podman

2. Clone and configure

3. Start services

Podman-specific notes

1. Install external dependencies

2. Install Python 3.12

3. Install OpenWatch

4. Install Kensa

5. Configure database

6. Run migrations

7. Start services

Prerequisites

Backend

Celery worker (separate terminal)

Frontend

Kensa

Production deployment

Post-install checklist

Environment variables

Troubleshooting

Getting started

Guides

Reference

​Prerequisites

​Deployment options

​1. Clone the repository

​2. Configure environment

​3. Start services

​4. Verify

​5. Log in

​6. Stop services

​1. Install Podman

​2. Clone and configure

​3. Start services

​Podman-specific notes

​1. Install external dependencies

​2. Install Python 3.12

​3. Install OpenWatch

​4. Install Kensa

​5. Configure database

​6. Run migrations

​7. Start services

​Prerequisites

​Backend

​Celery worker (separate terminal)

​Frontend

​Kensa

​Production deployment

​Post-install checklist

​Environment variables

​Troubleshooting

Prerequisites

Deployment options

1. Clone the repository

2. Configure environment

3. Start services

4. Verify

5. Log in

6. Stop services

1. Install Podman

2. Clone and configure

3. Start services

Podman-specific notes

1. Install external dependencies

2. Install Python 3.12

3. Install OpenWatch

4. Install Kensa

5. Configure database

6. Run migrations

7. Start services

Prerequisites

Backend

Celery worker (separate terminal)

Frontend

Kensa

Production deployment

Post-install checklist

Environment variables

Troubleshooting