Skip to content

Deployment Overview

WitFoo Analytics is a containerized security analytics platform deployed via Docker Compose or the WFA (WitFoo Appliance) CLI. This section covers all deployment methods, service configuration, monitoring, TLS, and the Conductor signal pipeline.

Supported Environments

OS Version Architecture Status
Ubuntu 22.04 LTS amd64 Fully supported
Ubuntu 24.04 LTS amd64 Fully supported

Hardware Requirements

Minimum hardware depends on the deployment role. See the WFA Deployment page for per-role specifications. All-in-One deployments require at least 8 CPU cores, 32 GB RAM, and 500 GB SSD storage.

Deployment Methods

Docker Compose

The standard deployment method for development and production environments. Five compose files support different deployment topologies.

# All-in-One (most common for single-node deployments)
docker compose -f docker/docker-compose.aio.yml up -d --build

See Docker Compose Reference for full details on all compose files and service definitions.

WFA CLI

The WFA (WitFoo Appliance) CLI automates installation, configuration, and upgrades for appliance-based deployments.

wfa analytics install --role analytics-aio

See WFA Deployment for the interactive configuration wizard and all CLI commands.

Deployment Roles

WitFoo Analytics supports four deployment roles that scale from a single node to a distributed cluster.

Role Description Services Use Case
AIO All-in-One 11 Analytics services Single-node deployments
AIO + Conductor All-in-One with signal pipeline 11 Analytics + 5 Conductor services Single-node with log collection
Data Node Cassandra storage node Cassandra only Distributed storage cluster
Processing Node Application services 10 services (no local Cassandra) Connects to external data nodes

Single-Node Architecture

The AIO role runs all services on a single machine. This is the simplest deployment and suitable for most organizations.

Browser --> Reverse Proxy (443/8081) --> API (8080) --> Incident Engine (8082)
                                    --> UI (3000)
                                    --> Dispatcher (8003)

Distributed Architecture

For larger deployments, separate data nodes (Cassandra) from processing nodes (application services).

Processing Node                    Data Node(s)
+-------------------+             +-------------------+
| API, UI, Engine   |  ------->  | Cassandra (9042)  |
| Proxy, Dispatcher |             +-------------------+
| NATS, Ingestion   |             +-------------------+
| Graph Processor   |  ------->  | Cassandra (9042)  |
| Prometheus, Grafana|            +-------------------+
+-------------------+

Service Overview

WitFoo Analytics consists of the following core services:

Service Port Description
reverse-proxy 443, 8081 HTTPS/HTTP entry point, routes to all backend services
api 8080 REST API, authentication, user management
incident-engine 8082 Incident analysis, work units, reporting
dispatcher 8003 Background job orchestration
artifact-ingestion 8090 Receives security artifacts via HTTP
graph-processor -- Background processor for graph node/edge creation
ui 3000 Svelte 5 web application
cassandra 9042 Primary data store (Cassandra 5.0)
nats 4222 Internal message broker
prometheus 9090 Metrics collection and storage
grafana 3001 Metrics dashboards and visualization

Quick Start

  1. Clone the repository and ensure Docker is installed.

  2. Start all services with the AIO compose file:

    cd docker
docker compose -f docker-compose.aio.yml up -d --build

  3. Wait for all health checks to pass (approximately 2-3 minutes):

    docker compose -f docker-compose.aio.yml ps

  4. Access the web UI at https://localhost or http://localhost:8081.

Default Credentials

The default administrator account is admin / F00theN0ise!. Change this password immediately after first login.

Production Readiness Checklist

Before deploying WitFoo Analytics to production, verify the following:

Load Balancer Configuration

  • HSTS headers enabled on the load balancer or reverse proxy (Strict-Transport-Security: max-age=31536000; includeSubDomains)
  • SSL termination configured with valid TLS certificates
  • Health check endpoint configured (e.g., /api/v1/status)

Trusted Proxies

  • Set WF_TRUSTED_PROXIES environment variable with the comma-separated list of trusted proxy IPs for correct forwarded header processing
  • Verify X-Forwarded-For, X-Forwarded-Proto, and X-Real-IP headers are passed correctly

Security Headers

The reverse-proxy automatically applies 7 OWASP security headers to all responses:

Header Value
X-Content-Type-Options nosniff
X-Frame-Options DENY
X-XSS-Protection 0
Referrer-Policy strict-origin-when-cross-origin
Content-Security-Policy Restrictive default policy
Permissions-Policy Restrictive feature policy
Strict-Transport-Security max-age=31536000; includeSubDomains

Database Credentials

  • Cassandra credentials are auto-generated per node during WFA installation -- do not use default credentials in production
  • Verify Cassandra is not exposed on public network interfaces

Network Hardening

  • Restrict internal service ports (8080, 8082, 8090, 4222, 9042) to the host or internal network only
  • Only expose the reverse-proxy port (443) externally
  • Configure firewall rules to limit inter-node communication to required ports

Environment Variables

See the Environment Variables reference for all security-related configuration options including WF_TRUSTED_PROXIES, AUTH_CONFIG_ENCRYPTION_KEY, and WF_JWT_SECRET.

Next Steps