This file provides guidance to agents when working with code in this repository.
- Configuration is Mandatory: The application will not start without the
KNOCKER_CONFIG_PATHenvironment variable pointing to a validknocker.yamlfile. Seeknocker.example.yamlfor the required structure. - IP Spoofing Risk: The service's security depends on the
trusted_proxieslist inknocker.yaml. If this is misconfigured, clients can easily spoof their IP address via theX-Forwarded-Forheader. - Astral Toolchain: This project uses
uvfor environment and dependency management,rufffor linting and formatting, andtyfor type checking. - Whitelist Persistence: The IP whitelist is stored in a simple JSON file (
/data/whitelist.jsoninside the container), not a database. The path is configured inknocker.yaml. - API Key Permissions: API keys have two important properties:
allow_remote_whitelist(boolean) andmax_ttl(integer). A key withallow_remote_whitelist: falsecan only whitelist its own source IP.max_ttldefines the maximum duration in seconds an IP can be whitelisted for with that key. - Development/Test Stacks: Every PR requires Python checks, Caddy (
dev/docker-compose.ci.yml), isolated FirewallD (dev/docker-compose.firewalld-ci.yml), and the original Linux host FirewallD suite (dev/docker-compose.ymlanddev/firewalld_integration_test.sh). The isolated stacks never mount host D-Bus or publish host ports. Runbash dev/test.sh linuxon a dedicated host with FirewallD 2.0+ for the full CI-equivalent suite, orbash dev/test.shfor the portable isolated subset.
-
Run All Tests After Changes: After making any code changes, you must run the local checks (
uv run pytest,uv run --group lint ruff check .,uv run --group lint ruff format --check ., anduv run --group type ty check) and the Docker-based integration tests using the standarddev/compose files plus the scripts underdev/. -
Create Git Commits: All work should be committed to Git.
-
github repo: FarisZR/knocker
-
Update Documentation: on any changes, you must update the documentation under the docs/ directory.