Castellan Build Guide

Overview

This guide provides comprehensive instructions for building Castellan from source code, including all dependencies, configuration requirements, and deployment options.

Prerequisites

Required Software

.NET 8.0 SDK or later
Docker Desktop (for Qdrant vector database)
Node.js 18+ (for Tailwind Dashboard interface)
PowerShell 5.1+ (Windows native)

AI Provider (Choose One)

Ollama (Recommended - Local AI)
OpenAI API Key (Cloud AI)

Optional Components

MaxMind GeoLite2 Databases (IP enrichment)
Git (for source code management)

Build Process

1. Clone Repository

git clone https://github.com/MLidstrom/castellan.git
cd castellan

2. Verify Prerequisites

# Check .NET SDK version
dotnet --version

# Check Docker status
docker --version

# Check Node.js version
node --version

# Check PowerShell version
$PSVersionTable.PSVersion

3. Build Core Application

# Restore NuGet packages
dotnet restore

# Build in Release mode
dotnet build -c Release

# Verify build success
dotnet build -c Release --no-restore --verbosity minimal

4. Build Tailwind Dashboard Interface

# Navigate to admin interface
cd dashboard

# Install dependencies
npm install

# Build production version
npm run build

# Return to root
cd ..

5. Build Docker Images (Optional)

# Build Castellan worker image
docker build -t castellan-worker -f src/Castellan.Worker/Dockerfile .

# Build React admin image
docker build -t dashboard -f dashboard/Dockerfile ./dashboard

Configuration

1. Application Configuration

# Copy configuration template
cd src/Castellan.Worker
Copy-Item appsettings.template.json appsettings.json

# Edit configuration file
notepad appsettings.json

2. Environment Variables

# Required authentication settings
$env:AUTHENTICATION__JWT__SECRETKEY = "your-secure-jwt-secret-key-minimum-64-characters"
$env:AUTHENTICATION__ADMINUSER__USERNAME = "admin"
$env:AUTHENTICATION__ADMINUSER__PASSWORD = "your-secure-password"

# AI Provider settings (Ollama recommended)
$env:EMBEDDINGS__PROVIDER = "Ollama"
$env:LLM__PROVIDER = "Ollama"

# Or OpenAI (if preferred)
# $env:OPENAI_API_KEY = "your-openai-api-key"
# $env:EMBEDDINGS__PROVIDER = "OpenAI"
# $env:LLM__PROVIDER = "OpenAI"

Deployment Options

Option 1: Automated Deployment (Recommended)

# Use automated startup script
.\scripts\start.ps1

# This will:
# 1. Start Qdrant vector database
# 2. Build and start Castellan Worker
# 3. Start Tailwind Dashboard interface
# 4. Verify all services are healthy

Option 2: Manual Deployment

# 1. Start Qdrant database
docker run -d --name qdrant -p 6333:6333 qdrant/qdrant

# 2. Start Castellan Worker
cd src/Castellan.Worker
dotnet run -c Release

# 3. Start Tailwind Dashboard (new terminal)
cd dashboard
npm start

# 4. Verify services
# - Qdrant: http://localhost:6333
# - Worker API: http://localhost:5000
# - Admin Interface: http://localhost:3000

Option 3: Docker Compose Deployment

# docker-compose.yml
version: '3.8'
services:
  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"
    volumes:
      - ./qdrant-data:/qdrant/storage
  
  castellan-worker:
    build:
      context: .
      dockerfile: src/Castellan.Worker/Dockerfile
    ports:
      - "5000:5000"
    depends_on:
      - qdrant
    environment:
      - QDRANT__HOST=qdrant
      - QDRANT__PORT=6333
  
  dashboard:
    build:
      context: ./dashboard
    ports:
      - "8080:80"
    depends_on:
      - castellan-worker

# Deploy with Docker Compose
docker-compose up -d

Testing and Validation

1. Run Unit Tests

# Run all tests
dotnet test

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

# Run specific test category
dotnet test --filter Category=Unit

2. Integration Testing

# Test connection to Qdrant
curl http://localhost:6333

# Test Worker API health
curl http://localhost:5000/health

# Test system status
curl http://localhost:5000/api/system-status

3. Performance Validation

# Check performance metrics
curl http://localhost:5000/api/system-status | jq '.data[] | select(.component=="Performance Monitor")'

# Verify connection pool status
curl http://localhost:5000/api/system-status | jq '.data[] | select(.component=="Qdrant Connection Pool")'

Build Optimization

Performance Builds

# Optimized release build
dotnet publish -c Release -r win-x64 --self-contained false

# AOT (Ahead-of-Time) compilation
dotnet publish -c Release -r win-x64 --self-contained true /p:PublishAot=true

Size Optimization

# Trimmed deployment
dotnet publish -c Release -r win-x64 --self-contained true /p:PublishTrimmed=true

# Single file deployment
dotnet publish -c Release -r win-x64 --self-contained true /p:PublishSingleFile=true

Troubleshooting

Common Build Issues

.NET SDK Version Mismatch

# Check global.json requirements
cat global.json

# Install correct SDK version
# Download from: https://dotnet.microsoft.com/download/dotnet

NuGet Package Restore Failures

# Clear NuGet cache
dotnet nuget locals all --clear

# Restore with verbose output
dotnet restore --verbosity detailed

Docker Build Issues

# Clean Docker build cache
docker builder prune

# Build with no cache
docker build --no-cache -t castellan-worker .

Node.js Build Issues

# Clear npm cache
npm cache clean --force

# Delete node_modules and reinstall
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install

Performance Issues

# Check system resources
Get-Process dotnet | Select-Object CPU, WorkingSet

# Monitor build performance
Measure-Command { dotnet build -c Release }

Build Verification Checklist

Build Success Indicators

.NET build completes without errors
All unit tests pass
React admin builds successfully
Docker images build (if using containers)
Configuration files are properly templated
All required services start successfully

Deployment Verification

Qdrant database is accessible on port 6333
Castellan Worker API responds on port 5000
Tailwind Dashboard interface loads on port 8080
System status API returns healthy status for all components
Connection pool shows healthy status
AI/ML services are properly configured and responding

Performance Validation

Event processing performs at expected rates (10K+ events/sec)
Memory usage is within expected bounds (<500MB)
Connection pool shows optimal utilization
AI analysis completes within expected timeframes (<4 seconds)

Next Steps

After successful build and deployment:

Configure Authentication: Set up secure admin credentials
Set Up AI Models: Install and configure Ollama models or OpenAI API
Configure Notifications: Set up Teams/Slack webhooks for alerts
Customize Detection Rules: Adjust security detection parameters
Monitor Performance: Use built-in performance dashboards

Support

If you encounter build issues:

GitHub Issues: Report build problems
Discussions: Community support
Documentation: Check other guides in the /docs folder

Castellan - Production-ready security monitoring with enterprise-grade build and deployment capabilities. 🏰

FilesExpand file tree

BUILD_GUIDE.md

Latest commit

History