Installation

Prerequisites

Docker and Docker Compose (the whole stack runs in containers).
Ruby 3.4+ and Python 3.14+ for local development (optional — everything runs in containers).
An INTERNAL_API_TOKEN for service-to-service auth.
At least one AI provider API key and threat-feed keys if you want LLM auditing and threat intelligence (both degrade gracefully when absent).

Steps

1. Clone the repository

git clone git@github.com:BitravenS/Pwn-Patch_Brand_Protection.git
cd brand_protect

2. Configure the environment

cp .env.example .env

Fill in the required values. At minimum you need:

INTERNAL_API_TOKEN — a shared secret used between the Rails app and the Python service. Generate one with openssl rand -hex 32.
RAILS_MASTER_KEY — the key for the Rails credentials file.
POSTGRES_PASSWORD — pick something other than the placeholder.

Optional but recommended:

OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY — for AI features.
Threat-feed keys — VIRUSTOTAL_API_KEY, ABUSEIPDB_API_KEY, SAFE_BROWSING_API_KEY, URLHAUS_API_KEY, SHODAN_API_KEY, SECURITYTRAILS_API_KEY, HACKERTARGET_API_KEY, CENSYS_API_KEY.

See Configuration for the full variable reference.

3. Build and start the stack

docker compose up --build

The first build compiles the Rails image and installs Python dependencies, so it takes a few minutes.

4. Verify the services

Service	URL
Rails dashboard	`http://localhost:3000`
Python API health	`http://localhost:8000/health`
GlitchTip (error tracking)	`http://localhost:8080`
Redis Insight	`http://localhost:5540`

Check the Python health endpoint returns {"status": "ok"} and the Rails app answers at /up.

5. Create an account

Open http://localhost:3000, sign up with an email and password, and log in.

What you get

PostgreSQL 16 — primary database (plus a separate brand_protect_glitchtip database for GlitchTip so its Django tables never pollute the Rails schema).
Rails 8.1 — the web app, on port 3000.
Python microservice — on port 8000.
Redis 7 — pub/sub transport for scan progress and findings.
GlitchTip — a self-hosted Sentry-compatible error tracker (web + Celery worker).
Redis Insight — a GUI for inspecting Redis state.

Ports and volumes

Named volumes persist postgres_data, redis_data, screenshots, and avatars across container restarts. The Rails and Python source directories are bind-mounted (./rails_web:/rails, ./services:/app) so code changes take effect on restart.

Troubleshooting

INTERNAL_API_TOKEN must be set in .env — the compose file fails fast if this variable is missing. Add it and docker compose up -d again.
Rails can’t reach the database — confirm Postgres is healthy: docker compose ps. The Rails container waits for the Postgres healthcheck.
Python logs a JSON format error — the python service honors LOG_FORMAT (json or text) and LOG_LEVEL from .env.

Next steps

Now that the stack is up, configure your brand profile and run your first scan.