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

Guided install (recommended)

The interactive install routine walks you through all important settings, produces a valid .env from .env.example, generates strong secrets (SECRET_KEY, DB password) and keeps DATABASE_URL in sync automatically. It is bilingual (German/English).

1. Clone the repository — fetches the complete stack (code, install.sh, docker-compose.yml, .env.example) from GitHub onto your server:

   # If Git is not installed yet (Debian/Ubuntu):
   sudo apt install -y git
   
   # Change to a directory of your choice, e.g. /opt:
   cd /opt
   
   # Clone the repository — this creates the subfolder "HumanShield.APP":
   git clone https://github.com/HumanShield-Awareness/HumanShield.APP.git
   
   # Enter the new folder — all following commands run from here:
   cd HumanShield.APP

   Notes:

   • After cloning you have the current state of the main branch. To run a specific version, check out the corresponding release tag, e.g. git checkout v0.15.0 (available versions: GitHub → Releases).
   • For updates later, run git pull in the same folder, then rebuild/start the stack with docker compose up -d --build.
   • Without Git it also works: download via Code → Download ZIP on the GitHub page and extract it. You lose the convenient update path via git pull, though.

2. Run the routine:

   ./install.sh

3. Follow the prompts (domain, database, admin account, SMTP, optional license). An empty field keeps the default.

4. Optionally let it start the stack right away at the end.

The routine only writes to .env (mode 600) — nothing is hard-wired in the code. An existing .env can optionally be reused as a base.

Quick start (manual)

1. Clone the repository (as described in "Guided install", step 1) 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