Docs

Requirements

Minimum sizing for a PoC deployment. heretix-api and heretix-management are separate Docker Compose stacks; totals below cover both.

CPU

2 vCPU minimum. The heretix-api app container can burst to roughly 70% of one core during data imports and searches; Postgres adds its own load while an import is running.

RAM

8GB minimum, 16GB recommended. Postgres for heretix-api is the dominant consumer (around 7.7GB with a full NVD mirror plus several OSV ecosystems loaded); the two app containers and heretix-management’s database use well under 1GB combined.

Disk

20GB to start. heretix-api’s database volume alone can reach around 11GB after months of accumulated NVD and OSV data; budget more if you import every OSV ecosystem heretix supports.

Software

Docker and Docker Compose v2.

Deploy heretix-apiGitHub

heretix-api aggregates NVD, OSV, CISA KEV, EPSS, and vendor advisories into a searchable database. It ships with its own PostgreSQL via Docker Compose.

1. Clone and configure

git clone https://github.com/TITeee/heretix-api
cd heretix-api
cp .env.example .env

Set API_KEY to a value of your choosing. heretix-cli and heretix-management both authenticate with it.

2. Start the stack

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

The API is now live at http://localhost:5000. GET /health checks it’s up; /dashboard shows import status (needs the same API_KEY).

3. Verify it’s running

curl http://localhost:5000/health
docker compose ps

Expect {"status":"ok",...} from the health check, and both containers listed as Up (the db container also shows healthy). If the app container keeps restarting, check docker compose logs -f app.

4. Update (later, when a new version is out)

git pull
docker compose up --build -d

Not part of the initial setup. Run it whenever you want to pick up new changes. Rebuilds the image and restarts the container; schema migrations and one-time backfills run automatically on every container start.

Import vulnerability data

A fresh database is empty. Run the initial import once before scanning anything.

docker compose exec app pnpm import:nvd full
docker compose exec app pnpm import:osv ecosystem npm
docker compose exec app pnpm import:osv ecosystem PyPI
docker compose exec app pnpm import:osv ecosystem Go

NVD’s full mirror (~240k CVEs) takes about 2.5 minutes with an NVD_API_KEY set in .env, or ~12 minutes without one. Import only the OSV ecosystems you actually scan. After the initial import, daily delta jobs and vendor advisory fetchers keep the database current automatically, with progress visible on /dashboard. Full ecosystem and vendor advisory list

Deploy heretix-managementGitHub

heretix-management is the web console for asset inventory, alert triage, and SLAs, and runs as its own Docker Compose stack with its own database.

1. Clone and configure

git clone https://github.com/TITeee/heretix-management
cd heretix-management
cp .env.example .env
# set AUTH_SECRET, AUTH_URL, HERETIX_API_URL, HERETIX_API_KEY

AUTH_SECRET: generate with openssl rand -base64 32. HERETIX_API_KEY must match the API_KEY set for heretix-api above. heretix-api and heretix-management are separate Compose projects. If both run on the same host, point HERETIX_API_URL at the host’s actual IP rather than localhost, since the management container can’t reach the api container through it.

2. Start and create the first user

docker compose build && docker compose up -d
docker compose exec app node_modules/.bin/tsx prisma/seed.ts

Default admin login is admin@example.com / changeme; override with SEED_EMAIL / SEED_PASSWORD. Open http://localhost:3000 and log in.

3. Verify it’s running

docker compose ps
docker compose logs -f app

The db container shows healthy once Postgres accepts connections; the app container has no built-in health check, so confirm it isn’t restarting and that the login page loads at http://localhost:3000.

4. Update (later, when a new version is out)

git pull
docker compose build && docker compose up -d

Not part of the initial setup. Run it whenever you want to pick up new changes. Database migrations run automatically on container start; the seed command from step 2 only needs to run once.

Quick Start (CLI)GitHub

With both services running, scan a host and bring findings into heretix-management. Download the heretix-cli binary for your platform (Linux amd64/arm64, Windows amd64) from the releases page, or build it from source with go build.

# Scan the current host
heretix-cli scan --api-url http://heretix-api:5000 --api-key YOUR_KEY

# Or collect packages only (offline), as a CycloneDX SBOM
heretix-cli collect -o inventory.json

# Offline supply-chain scan, no API required.
# Exit code 1 on findings fails the CI job.
heretix-cli detect --scan-path .

# In heretix-management, open an asset and import inventory.json
# via the "Import Inventory" button in the asset detail page

# Click "Scan" on the asset page, or use the CLI directly
heretix-cli check inventory.json --api-url http://heretix-api:5000

# Submit inventory to GitHub Dependency Submission API
heretix-cli submit inventory.json \
  --token $GITHUB_TOKEN \
  --repo owner/repo \
  --sha $SHA \
  --ref $REF