Installation.en

Deutsch | English

Installation

HumanShield.APP runs as a Docker Compose stack. All environment-specific values come from a .env — no values are hard-wired in the code.

Requirements

• Docker Engine (recent version, ≥ 24) and Docker Compose v2 — this is the current docker compose plugin integrated into Docker (invoked with a space). Compose v2 is the current generation (2.x releases); the old, separate docker-compose (v1, Python) is discontinued and not supported. Check with docker compose version.
• A domain or an upstream reverse proxy (optional, but recommended for TLS)
• An SMTP mailbox for sending mail (any provider)

Hardware requirements

The entire stack (PostgreSQL, Redis, FastAPI backend, frontend, Caddy) runs on one Docker host. The values are guidelines; demand grows with the number of recipients, concurrent usage and optional business features (PDF reports, AI integration).

Resource	Minimum	Recommended
CPU	2 vCPU	2–4 vCPU
RAM	2 GB	4 GB
Disk	15 GB SSD	20–40 GB SSD
Operating system	Linux (x86-64 or ARM64) with Docker Engine (≥ 24) + Docker Compose v2 (docker compose)	same

Component sizing (idle reference values): PostgreSQL ~150 MB, Redis ~30 MB, backend (Python/uvicorn incl. add-ons) ~300 MB, frontend ~300 MB, Caddy ~40 MB. Short-term peaks occur during PDF generation, AI calls and large send batches.

Notes:

• Minimum is sufficient for smaller organizations (up to a few hundred recipients, occasional campaigns).
• Recommended provides headroom for larger campaigns, reporting/AI and the tracking data that grows with each campaign.
• An SSD is recommended for the database (many small writes from tracking events).
• Network: outbound SMTP access (sending) and reachability of APP_DOMAIN for the target persons (tracking).
• The optional GeoIP country lookup requires a local MMDB file (~10–60 MB, see Configuration).

Components

Service	Role
postgres	Database
redis	Cache/queue
backend	API (FastAPI)
frontend	Dashboard (React/Vite)
caddy	Reverse proxy / TLS

Quick start

1. Clone the repository and copy .env.example to .env.
2. Fill .env with real values (see below) — never commit it.
3. Start the stack:

   docker compose up -d

4. Database migrations run automatically when the backend starts.
5. Open the dashboard via the configured domain (or https://localhost).

Important .env values (generic)

# App / domain
APP_DOMAIN=humanshield.example.com
CADDY_SITE_ADDRESS=humanshield.example.com   # or ":80" behind an external TLS proxy

# Database
POSTGRES_DB=humanshield
POSTGRES_USER=humanshield
POSTGRES_PASSWORD=change-me-strong-password

# Security
SECRET_KEY=change-me-min-32-characters-random

# First admin (only effective on the very first start)
INITIAL_ADMIN_EMAIL=admin@example.com
INITIAL_ADMIN_PASSWORD=change-me

# SMTP (any provider)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=noreply@example.com
SMTP_PASSWORD=change-me
SMTP_FROM_EMAIL=noreply@example.com
SMTP_FROM_NAME=HumanShield-Awareness
SMTP_TLS_MODE=starttls

First login

On the first start, an admin account is created from INITIAL_ADMIN_EMAIL / INITIAL_ADMIN_PASSWORD. Afterwards, manage further accounts under Users and change the initial password.

Add-ons & backend restart

The paid Business and Enterprise add-ons are mounted into the backend container as separate packages (via volume to /addons/…) and loaded automatically when the backend starts.

⚠️ Important for add-on changes: The backend runs with uvicorn --reload, which only watches the app directory — not the mounted add-on packages. Changes to add-on code (new routes, fields, etc.) therefore only take effect after a manual backend restart:

docker compose restart backend

Symptom if the restart is forgotten: the frontend calls a new add-on route that does not yet exist in the running process (HTTP 404) and shows a generic error. After the restart the route is available.

Tracking reachability

Open/click tracking only works if recipients can reach the address set in APP_DOMAIN. For purely internal/VPN domains, external recipients register no events. Many mail clients also block the open pixel — clicks are therefore the more reliable signal.

See also: Configuration