diff --git a/README.md b/README.md index 80a025df..878895f8 100644 --- a/README.md +++ b/README.md @@ -68,11 +68,42 @@ This makes it well-suited for: |----------|---------|---------| | Docker | Latest | Container runtime | | Docker Compose | Latest | Multi-container orchestration | -| LLM Server | Any OpenAI-compatible API | AI features (e.g., LM Studio, Ollama, OpenAI) | +| LLM Server | Any OpenAI-compatible API, self- or LAN-hosted | AI features (e.g., LM Studio, Ollama) | **Minimum Hardware:** -- RAM: 4GB (8GB+ recommended) -- Storage: 10GB (for database, PCAP files, and object storage) + +The default stack's enforced container limits total ~4.4GB (~5.4GB with the Keycloak +auth overlay), so size the host above that — see +[Container Resource Limits](docs/operations/production-hardening.rst) for the +per-service breakdown. + +These tiers size the TracePcap stack **only** — AI features disabled, or +`LLM_BASE_URL` pointed at a separate inference server on the same local network. +TracePcap must run fully offline, so `LLM_BASE_URL` must not reference a public +or internet-hosted API. + +| | Minimum | Recommended | Comfortable | +|---|---------|-------------|-------------| +| RAM | 6GB (with `SURICATA_ENABLED=false`) | 8GB+ | 16GB | +| CPU | 4 cores | 4+ cores for fast nDPI analysis | 8 cores | +| Storage | 10GB (database, PCAP files, object storage) | 50GB+ for large PCAP collections | 100GB+ SSD | + +**Comfortable** assumes Suricata enabled and routine work on large captures. Raise the +`.env` defaults to match — the shipped `APP_MEMORY_MB=2048` caps uploads at 512MB, since +max upload is 25% of the backend budget: + +```ini +APP_MEMORY_MB=8192 # 4 GB heap, 2 GB max upload +BACKEND_CPU_LIMIT=6 +POSTGRES_MEM_LIMIT=2g +MINIO_MEM_LIMIT=1g +SURICATA_ENABLED=true # the default; set explicitly if lowered for Minimum +``` + +**GPU:** not used by TracePcap — packet dissection and threat detection are CPU-bound, +and no container requests a GPU device. A GPU only matters if you self-host the LLM, +where it is that server's requirement: ~8GB VRAM for a 7B model, ~16GB for a 14B +(quantised), plus 5–30GB of storage for weights, **on top of** the tiers above. ### Installation diff --git a/docs/getting-started/prerequisites.rst b/docs/getting-started/prerequisites.rst index c4780b43..3b6d4239 100644 --- a/docs/getting-started/prerequisites.rst +++ b/docs/getting-started/prerequisites.rst @@ -24,21 +24,79 @@ Software Requirements Hardware Requirements --------------------- +All three tiers below size the TracePcap stack **only**. They assume AI features +are either disabled or pointed via ``LLM_BASE_URL`` at a separate inference +server on the same local network. TracePcap must function fully offline, so +``LLM_BASE_URL`` must never reference a public or internet-hosted API. Running +the LLM on the TracePcap host itself adds to every figure — see the note at the +end of this section. + **Minimum:** -- RAM: 4 GB +- RAM: 6 GB, with ``SURICATA_ENABLED=false`` +- CPU: 4 cores - Storage: 10 GB (database, PCAP files, object storage) **Recommended:** - RAM: 8 GB or more -- Storage: 50 GB+ for large PCAP collections - CPU: 4+ cores for fast nDPI analysis +- Storage: 50 GB+ for large PCAP collections + +**Comfortable** — Suricata enabled, routine work on large captures: + +- RAM: 16 GB +- CPU: 8 cores +- Storage: 100 GB+ SSD + +At this tier, raise the defaults in ``.env`` — the shipped ``APP_MEMORY_MB=2048`` +caps uploads at 512 MB, which is usually the first limit reached: + +.. code-block:: ini + + APP_MEMORY_MB=8192 # 4 GB heap, 2 GB max upload + BACKEND_CPU_LIMIT=6 + POSTGRES_MEM_LIMIT=2g + MINIO_MEM_LIMIT=1g + SURICATA_ENABLED=true # the default; set explicitly if lowered for Minimum + +An SSD matters here: Postgres analysis history, MinIO object storage, and nginx +spilling large request bodies to ``/tmp`` are all disk-bound before they are +memory-bound. + +.. note:: + + The Comfortable tier is an operational recommendation, not a measured + benchmark. It is derived from the backend guidance in + :doc:`../operations/production-hardening` (4 GB+ for the backend alone with + Suricata on captures over 100 MB), with headroom for the rest of the stack. + +.. important:: + + The default stack declares ~4.4 GB of enforced container memory limits + (~5.4 GB with an authentication overlay), before the host OS and Docker + itself — a 4 GB host cannot run it at default settings. See + :doc:`../operations/production-hardening` for the per-service breakdown and + the environment variables that override each limit. + + ``.env.example`` ships ``SURICATA_ENABLED=true``, for which 4 GB+ for the + backend alone is recommended on captures over 100 MB. Budget 8 GB+ if you + keep Suricata enabled. .. note:: - If you plan to run an LLM locally for AI features, allocate additional RAM - (8–16 GB typical for a 7B–14B parameter model). + TracePcap itself never uses a GPU — packet dissection (tshark, nDPI) and + threat detection (Suricata) are CPU-bound, and no container in the stack + requests a GPU device. + + A GPU is relevant only when self-hosting the LLM, and it is that server's + requirement rather than TracePcap's. Budget roughly 8 GB of VRAM for a 7B + parameter model or 16 GB for a 14B, quantised, plus 5–30 GB of storage for + model weights, **on top of** the tiers above. CPU-only inference works but is + slow enough that long generations such as Story Mode may approach the proxy + timeout. Pointing ``LLM_BASE_URL`` at an LLM server on another machine — which + still satisfies the offline requirement on a local network — leaves the tiers + above unchanged. Operating System ----------------