Quickstart Guide

Looking for an easier way? Use our Desktop Installer for one-click deployment with automatic configuration. No command line required!

Prerequisites

Before you begin, make sure you have the following installed on your system:

Docker Engine (20.10.0 or higher)
Docker Compose (v2.0.0 or higher)
OpenSSL (for generating SSL certificates)

Installing Docker

For macOS:

Download and install Docker Desktop from Docker Hub
Follow the installation wizard
Verify installation:

docker --version
docker compose --version

For Linux (Ubuntu/Debian):

# Update package index
sudo apt-get update

# Install prerequisites
sudo apt-get install \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

# Add Docker's official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Set up stable repository
echo \
  "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Add your user to docker group
sudo usermod -aG docker $USER

For Windows:

Download and install Docker Desktop from Docker Hub
Enable WSL 2 following Docker’s documentation
Follow the installation wizard
Verify installation in PowerShell:

docker --version
docker compose --version

Step 1: Create Project Directory

Create a new directory for your CaseBender deployment and navigate into it:

mkdir casebender-deployment
cd casebender-deployment

Step 2: Configure Environment Variables

Create a .env file with the following content:

# Authentication
AUTH_SECRET="B7OawnWf6+LwB/9yXbxbk4ppZ1khydqj4qc9k9g3nnE="
AUTH_SALT="B7OawnW"
AUTH_TRUST_HOST=true
NEXTAUTH_URL=https://local.casebender.com
NEXTAPP_URL=https://local.casebender.com

# License (optional)
# CaseBender auto-generates and persists a license secret key on first boot
# (stored in the "casebender_secret" volume) and reuses it across restarts and
# updates — no action required. Only set LICENSE_SECRET_KEY if you want to manage
# the key yourself: back it up, rotate it, or share it across replicas.
# Generate one with: openssl rand -hex 32
# LICENSE_SECRET_KEY=

# Liveblocks Configuration (real-time collaboration)
LIVEBLOCKS_SECRET_KEY=sk_dev_HaIczPV4gPit5_gx7YRsNXLGJNzBE5wQ8z8I1H8ft3ZPZHVrfH2ryJJ586ezHYla

# Database Configuration (host is the internal "db" service)
POSTGRES_PASSWORD=88AlwaysTimeToWin88
POSTGRES_PRISMA_URL="postgresql://superadmin:88AlwaysTimeToWin88@db:5432/casebender?schema=public"
POSTGRES_URL="postgresql://superadmin:88AlwaysTimeToWin88@db:5432/casebender?schema=public"
POSTGRES_URL_NON_POOLING="postgresql://superadmin:88AlwaysTimeToWin88@db:5432/casebender?schema=public"

# Redis Configuration
REDIS_URL="redis://redis:6379"
# Discrete host/port fallback — read by every service (also covers older
# images that don't parse REDIS_URL for the background job queue).
REDIS_HOST=redis
REDIS_PORT=6379

CaseBender runs as several containers: the web app (app), a REST API gateway (api), an alert ingestion gateway (ingestion, this is what receives integration webhooks such as Microsoft Defender), a background worker, and the workflow and MISP processors. Nginx sits in front and routes traffic to the right service. All of these are included in the Compose file below.

Step 3: Generate SSL Certificates

For local development, generate self-signed SSL certificates:

# Generate SSL certificate and key
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout local-casebender.key \
  -out local-casebender.crt \
  -subj "/CN=local.casebender.com/O=CaseBender/C=US"

# Verify the certificate
openssl x509 -in local-casebender.crt -text -noout

Step 4: Configure Nginx

Create nginx.conf with the following content:

events {
    worker_connections 1024;
}

http {
    # ─── Upstreams ─────────────────────────────────────────────
    upstream web_app {
        server app:3000;
    }

    upstream api_service {
        server api:3005;
    }

    upstream ingestion_service {
        server ingestion:3003;
    }

    # ─── Rate Limiting ─────────────────────────────────────────
    limit_req_zone $binary_remote_addr zone=api_limit:10m rate=100r/s;
    limit_req_zone $binary_remote_addr zone=ingest_limit:10m rate=1000r/s;

    # ─── HTTP -> HTTPS Redirect ────────────────────────────────
    server {
        listen 80;
        server_name local.casebender.com;
        return 301 https://$server_name$request_uri;
    }

    # ─── Main HTTPS Server ─────────────────────────────────────
    server {
        listen 443 ssl;
        http2 on;
        server_name local.casebender.com;

        ssl_certificate /etc/nginx/certs/local-casebender.crt;
        ssl_certificate_key /etc/nginx/certs/local-casebender.key;

        ssl_protocols TLSv1.2 TLSv1.3;
        client_max_body_size 100M;

        # ─── Security Headers ─────────────────────────────────
        add_header X-Frame-Options "SAMEORIGIN" always;
        add_header X-Content-Type-Options "nosniff" always;
        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

        # ─── Ingestion API (integration webhooks) ─────────────
        location /api/v1/ingest/ {
            limit_req zone=ingest_limit burst=500 nodelay;
            proxy_pass http://ingestion_service;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }

        # Legacy ingestion route
        location /api/ingest/ {
            limit_req zone=ingest_limit burst=500 nodelay;
            proxy_pass http://ingestion_service;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }

        # ─── REST API Gateway ─────────────────────────────────
        location /api/v1/ {
            limit_req zone=api_limit burst=50 nodelay;
            proxy_pass http://api_service;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }

        location /api/openapi.json {
            proxy_pass http://api_service;
            proxy_set_header Host $host;
        }

        # ─── Health Check ─────────────────────────────────────
        location /health {
            access_log off;
            return 200 "healthy";
            add_header Content-Type text/plain;
        }

        # ─── Web Application (catch-all) ──────────────────────
        location / {
            proxy_pass http://web_app;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Forwarded-Host $host;
            proxy_set_header X-Forwarded-Port $server_port;

            # WebSocket support
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";

            proxy_connect_timeout 60s;
            proxy_send_timeout 60s;
            proxy_read_timeout 60s;
        }
    }
}

Step 5: Create Docker Compose Configuration

Create docker-compose.yml with the following content:

services:
  # ─── Core Services ───────────────────────────────────────────
  app:
    image: casebender/casebender:latest
    platform: linux/amd64
    ports:
      - "3000:3000"
    environment:
      - AUTH_SECRET=${AUTH_SECRET}
      - AUTH_SALT=${AUTH_SALT}
      - AUTH_TRUST_HOST=true
      - NEXTAUTH_URL=${NEXTAUTH_URL:-https://local.casebender.com}
      - NEXTAPP_URL=${NEXTAPP_URL:-https://local.casebender.com}
      - LICENSE_SECRET_KEY=${LICENSE_SECRET_KEY}
      - LIVEBLOCKS_SECRET_KEY=${LIVEBLOCKS_SECRET_KEY}
      - POSTGRES_PRISMA_URL=${POSTGRES_PRISMA_URL}
      - POSTGRES_URL=${POSTGRES_URL}
      - POSTGRES_URL_NON_POOLING=${POSTGRES_URL_NON_POOLING}
      - REDIS_URL=${REDIS_URL:-redis://redis:6379}
      - REDIS_HOST=${REDIS_HOST:-redis}
      - REDIS_PORT=${REDIS_PORT:-6379}
    volumes:
      # Persists the auto-generated license secret + blob across image updates
      # so `docker compose pull` never regenerates the license.
      - casebender_secret:/app/apps/web/app/secret
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "node -e \"require('http').get('http://localhost:3000/api/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))\""]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 60s

  api:
    image: casebender/api:latest
    platform: linux/amd64
    ports:
      - "3005:3005"
    environment:
      - PORT=3005
      - POSTGRES_PRISMA_URL=${POSTGRES_PRISMA_URL}
      - POSTGRES_URL=${POSTGRES_URL}
      - POSTGRES_URL_NON_POOLING=${POSTGRES_URL_NON_POOLING}
      - REDIS_URL=${REDIS_URL:-redis://redis:6379}
      - REDIS_HOST=${REDIS_HOST:-redis}
      - REDIS_PORT=${REDIS_PORT:-6379}
      - AUTH_SECRET=${AUTH_SECRET}
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped

  ingestion:
    image: casebender/ingestion:latest
    platform: linux/amd64
    ports:
      - "3003:3003"
    environment:
      - PORT=3003
      - POSTGRES_PRISMA_URL=${POSTGRES_PRISMA_URL}
      - POSTGRES_URL=${POSTGRES_URL}
      - POSTGRES_URL_NON_POOLING=${POSTGRES_URL_NON_POOLING}
      - REDIS_URL=${REDIS_URL:-redis://redis:6379}
      - REDIS_HOST=${REDIS_HOST:-redis}
      - REDIS_PORT=${REDIS_PORT:-6379}
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped

  # ─── Processing Services ─────────────────────────────────────
  worker:
    image: casebender/worker:latest
    platform: linux/amd64
    ports:
      - "3002:3002"
    environment:
      - PORT=3002
      - POSTGRES_PRISMA_URL=${POSTGRES_PRISMA_URL}
      - POSTGRES_URL=${POSTGRES_URL}
      - POSTGRES_URL_NON_POOLING=${POSTGRES_URL_NON_POOLING}
      - REDIS_URL=${REDIS_URL:-redis://redis:6379}
      - REDIS_HOST=${REDIS_HOST:-redis}
      - REDIS_PORT=${REDIS_PORT:-6379}
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped

  workflow-processor:
    image: casebender/workflow-processor:latest
    platform: linux/amd64
    ports:
      - "3001:3001"
    environment:
      - POSTGRES_PRISMA_URL=${POSTGRES_PRISMA_URL}
      - POSTGRES_URL=${POSTGRES_URL}
      - POSTGRES_URL_NON_POOLING=${POSTGRES_URL_NON_POOLING}
      - REDIS_URL=${REDIS_URL:-redis://redis:6379}
      - REDIS_HOST=${REDIS_HOST:-redis}
      - REDIS_PORT=${REDIS_PORT:-6379}
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
      app:
        condition: service_healthy
    restart: unless-stopped

  misp-processor:
    image: casebender/misp-processor:latest
    platform: linux/amd64
    ports:
      - "3004:3004"
    environment:
      - PORT=3004
      - POSTGRES_PRISMA_URL=${POSTGRES_PRISMA_URL}
      - POSTGRES_URL=${POSTGRES_URL}
      - POSTGRES_URL_NON_POOLING=${POSTGRES_URL_NON_POOLING}
      - REDIS_URL=${REDIS_URL:-redis://redis:6379}
      - REDIS_HOST=${REDIS_HOST:-redis}
      - REDIS_PORT=${REDIS_PORT:-6379}
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
      app:
        condition: service_healthy
    restart: unless-stopped

  # ─── Infrastructure ──────────────────────────────────────────
  db:
    image: postgres:17
    environment:
      POSTGRES_USER: superadmin
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-88AlwaysTimeToWin88}
      POSTGRES_DB: casebender
    ports:
      - "5433:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U superadmin -d casebender"]
      interval: 5s
      timeout: 5s
      retries: 10
      start_period: 30s
    restart: unless-stopped

  redis:
    image: redis:7.2-alpine
    command: redis-server --protected-mode no
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    restart: unless-stopped

  minio:
    image: quay.io/minio/minio
    mem_limit: 512m
    command: ["minio", "server", "/data", "--console-address", ":9090"]
    environment:
      - MINIO_ROOT_USER=minioadmin
      - MINIO_ROOT_PASSWORD=minioadmin
    ports:
      - "9090:9090"
      - "9000:9000"
    volumes:
      - "miniodata:/data"
    restart: unless-stopped

  # ─── Reverse Proxy ───────────────────────────────────────────
  nginx:
    image: nginx:alpine
    ports:
      - "443:443"
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./local-casebender.crt:/etc/nginx/certs/local-casebender.crt:ro
      - ./local-casebender.key:/etc/nginx/certs/local-casebender.key:ro
    depends_on:
      app:
        condition: service_healthy
    restart: unless-stopped

volumes:
  miniodata:
  pgdata:
  redis_data:
  casebender_secret:

Need enterprise search (OpenSearch)? The Desktop Installer can add the search-sync, opensearch, and opensearch-dashboards services for you. For most local evaluations the default PostgreSQL-based search above is all you need.

Step 6: Configure Local DNS

Add the following entry to your hosts file:

For macOS and Linux:

sudo echo "127.0.0.1 local.casebender.com" >> /etc/hosts

For Windows:

Add the following line to C:\Windows\System32\drivers\etc\hosts:

127.0.0.1 local.casebender.com

Step 7: Start the Application

Pull the required images:

docker compose pull

Start all services:

docker compose up -d

Monitor the logs:

docker compose logs -f

Access the application at https://local.casebender.com

After deploying CaseBender, you can log in with the following default credentials:

Username: admin@casebender.app
Password: secret1234

For security reasons, we strongly recommend changing these default credentials immediately after your first login.

Running behind a corporate proxy

If your host can only reach the internet through a corporate HTTP proxy (“proxy-only” networks), CaseBender’s outbound calls — license activation and integrations such as Microsoft Defender and Splunk — must be routed through it. Add the proxy variables to your .env:

HTTP_PROXY=http://proxy.example.com:8080
HTTPS_PROXY=http://proxy.example.com:8080
# Internal Docker services (and any on-prem targets) MUST bypass the proxy:
NO_PROXY=127.0.0.1,localhost,db,redis,minio,api,ingestion,worker,workflow-processor,misp-processor,search-sync,opensearch

Then pass them to every CaseBender service by adding these lines to each service’s environment: block in docker-compose.yml:

      - HTTP_PROXY=${HTTP_PROXY:-}
      - HTTPS_PROXY=${HTTPS_PROXY:-}
      - NO_PROXY=${NO_PROXY:-}

NO_PROXY must include the internal Docker service names above. Otherwise container-to-container traffic (e.g. the web app calling the ingestion service) is sent to the corporate proxy and fails — breaking the app even though it has nothing to do with the internet.

Which targets go through the proxy? Public endpoints must go through the proxy and must NOT be in NO_PROXY — e.g. Microsoft Defender (login.microsoftonline.com, graph.microsoft.com). On-prem targets should be listed in NO_PROXY so they are reached directly — e.g. an internal Splunk HEC. If you use Splunk Cloud, leave it out so it routes through the proxy.

Verify connectivity from inside a container (uses node, no curl needed):

docker compose exec app node -e "fetch('https://login.microsoftonline.com/',{signal:AbortSignal.timeout(5000)}).then(r=>console.log('OK',r.status)).catch(e=>console.log('FAIL',e.message))"

When a proxy is configured, each service logs [proxy] Outbound fetch routed through corporate proxy (...) on startup.

Troubleshooting

Common Issues

Certificate Warnings:
- The browser will show a security warning because we’re using a self-signed certificate
- Click “Advanced” and proceed to the website
- For development purposes, this is expected and safe
Port Conflicts:
- Ensure ports 80, 443, 3000, 3001, 3002, 3003, 3004, 3005, 5433, 6379, 9000, and 9090 are not in use
- If needed, modify the port mappings in docker-compose.yml
Database Connection:
- Check PostgreSQL logs: docker compose logs db
- Verify database credentials in .env
- Ensure the database is running: docker compose ps db
Service Dependencies:
- If services fail to start, check their dependencies:
docker compose ps docker compose logs [service_name]

Checking Logs

View logs for specific services:

# All services
docker compose logs

# Specific service
docker compose logs [service_name]

# Follow logs
docker compose logs -f [service_name]

Service Management

# Restart a specific service
docker compose restart [service_name]

# Stop all services
docker compose down

# Remove volumes (will delete all data)
docker compose down -v

Next Steps

Now that you have CaseBender running locally, you might want to:

Production Deployment

Deploy CaseBender to your production environment

Configuration

Learn about advanced configuration options

Getting Started

Deployment

Alert Management

Case Management

Task Management

Time Tracking

Analytics

Audits

Settings

Prerequisites

Installing Docker

For macOS:

For Linux (Ubuntu/Debian):

For Windows:

Step 1: Create Project Directory

Step 2: Configure Environment Variables

Step 3: Generate SSL Certificates

Step 4: Configure Nginx

Step 5: Create Docker Compose Configuration

Step 6: Configure Local DNS

For macOS and Linux:

For Windows:

Step 7: Start the Application

Running behind a corporate proxy

Troubleshooting

Common Issues

Checking Logs

Service Management

Next Steps

Production Deployment

Configuration

​Prerequisites

​Installing Docker

​For macOS:

​For Linux (Ubuntu/Debian):

​For Windows:

​Step 1: Create Project Directory

​Step 2: Configure Environment Variables

​Step 3: Generate SSL Certificates

​Step 4: Configure Nginx

​Step 5: Create Docker Compose Configuration

​Step 6: Configure Local DNS

​For macOS and Linux:

​For Windows:

​Step 7: Start the Application

​Default Login Credentials

​Running behind a corporate proxy

​Troubleshooting

​Common Issues

​Checking Logs

​Service Management

​Next Steps

Production Deployment

Configuration

Prerequisites

Installing Docker

For macOS:

For Linux (Ubuntu/Debian):

For Windows:

Step 1: Create Project Directory

Step 2: Configure Environment Variables

Step 3: Generate SSL Certificates

Step 4: Configure Nginx

Step 5: Create Docker Compose Configuration

Step 6: Configure Local DNS

For macOS and Linux:

For Windows:

Step 7: Start the Application

Default Login Credentials

Running behind a corporate proxy

Troubleshooting

Common Issues

Checking Logs

Service Management

Next Steps