Repository: jclee941/blacklist
Current version: See VERSION, tracked in CHANGELOG.md.
Blacklist is a containerized platform for collecting, managing, and distributing IP blacklist data. It combines a Flask API, an isolated collector service, a Next.js dashboard, PostgreSQL, and Redis.
| Service | Technology | Listener | Purpose |
|---|---|---|---|
| App | Flask, Python 3.11 | internal 2542 |
REST API, blacklist management, Fortinet integration, settings, and monitoring |
| Frontend | Next.js 15, React 19 | container 3000, host 443 |
Dashboard and browser proxy for the Flask API |
| Collector | Python 3.11 | internal 8545 |
Scheduled and manual blacklist source collection |
| PostgreSQL | PostgreSQL 15 | internal 5432 |
Persistent data |
| Redis | Redis 7 | internal 6379 |
Supporting cache and service state |
Requirements: Docker and Docker Compose v2. Copy the development template to deploy/.env, populate its required secrets, and expose the local WARP proxy to host.docker.internal:40000. Internal TLS material defaults to BLACKLIST_TLS_DIR=/etc/blacklist/tls; a packaged installation provisions this directory automatically through deploy/install.sh.
cp deploy/.env.example deploy/.env
# Edit deploy/.env and set the required credentials and encryption secrets.
make dev
curl --fail --insecure https://localhost:443/healthThe packaged frontend is the external endpoint on host port 443 and requires an operator-provided certificate matching FRONTEND_TLS_SERVER_NAME. Explicit self-signed mode is loopback-only for development. Flask, the collector, PostgreSQL, and Redis communicate over internal TLS using certificates from BLACKLIST_TLS_DIR (default /etc/blacklist/tls), listening on 2542, 8545, 5432, and 6379. For standalone frontend development, run cd frontend && npm run dev; it listens on http://localhost:2543.
- The Next.js dashboard sends API requests through
frontend/lib/api.ts. frontend/next.config.tssupplies development rewrites; packaged production traffic is proxied byfrontend/server.jsusingfrontend/server-routing.js.- Flask handles blacklist, collection, Fortinet, settings, and monitoring APIs.
- The collector runs independently, stores collection results through its service boundaries, and exposes health and status on port
8545. - PostgreSQL persists application data and Redis supplies supporting state.
JWT token APIs are available at /api/auth/login, /api/auth/me, and /api/auth/verify. Dashboard and protected API routes require a valid administrator JWT by default; login, health, metrics, and static assets remain open. Fortinet feeds are exempt from the administrator JWT but still require the configured feed bearer token and allowed source network. Configure credentials and signing material with environment variables or the settings store. DISABLE_JWT_AUTH=true is reserved for explicit development use.
make help
make verify-lint
make test
cd frontend && npm run typecheckSee frontend/README.md for dashboard work and collector/README.md for collector operation.
.github/workflows/ci.yml is the primary pull request and master CI workflow. It runs changed-area checks, builds images, scans images, and runs browser E2E tests.
Release from a clean master checkout with:
make release TYPE=patch
# or preview the release
make release-dry TYPE=minorscripts/release.sh prepares and pushes the version commit, waits for successful CI on that exact commit, and only then creates and pushes the annotated tag. The tag triggers .github/workflows/release.yml to rebuild, test, scan, package, sign, publish GHCR images, and create the GitHub Release.
Files in docs/wiki/ and docs/deliverables/ are historical records. They may describe earlier releases and aren't the source of current runtime, ownership, authentication, CI, or release behavior.