name	docker-vigil-orchestration
description	Docker Compose orchestration for Vigil Guard v2.0.0 microservices (11 services). Use when deploying services, managing containers, troubleshooting Docker network issues, working with vigil-net, configuring docker-compose.yml, handling service dependencies, or working with 3-branch detection services (heuristics, semantic, prompt-guard).
version	2.0.0
allowed-tools	Read, Write, Bash, Grep, Glob

Docker Orchestration for Vigil Guard v2.0.0

Overview

Multi-service Docker deployment orchestration for Vigil Guard's 3-branch parallel detection architecture with 11 microservices.

When to Use This Skill

Starting/stopping services
Debugging container issues
Managing Docker network (vigil-net)
Modifying docker-compose.yml
Viewing service logs
Checking service health
Troubleshooting port conflicts
Understanding service dependencies
Managing 3-branch detection services

Service Architecture (v2.0.0)

All Services (11 containers)

services:
  # 3-Branch Detection Engine
  heuristics-service:    # Branch A - Pattern detection (5005)
  semantic-service:      # Branch B - Embedding similarity (5006)
  prompt-guard-api:      # Branch C - LLM safety (8000)

  # PII & Language Detection
  presidio-pii-api:      # Dual-language PII detection (5001)
  language-detector:     # Hybrid language detection (5002)

  # Core Platform
  n8n:                   # Workflow engine - 24-node pipeline (5678)
  web-ui-backend:        # Express API server (8787)
  web-ui-frontend:       # React SPA (80 internal)

  # Monitoring Stack
  clickhouse:            # Analytics database (8123, 9000)
  grafana:               # Dashboards (3001)

  # Infrastructure
  caddy:                 # Reverse proxy (80, 443)

Service Ports

Service	Internal Port	External Port	Purpose
heuristics-service	5005	5005	Branch A detection
semantic-service	5006	5006	Branch B detection
prompt-guard-api	8000	8000	Branch C detection
presidio-pii-api	5001	5001	PII detection
language-detector	5002	5002	Language detection
n8n	5678	5678	Workflow engine
web-ui-backend	8787	8787	Config API
web-ui-frontend	80	-	React UI (via Caddy)
clickhouse	8123, 9000	8123, 9000	Analytics DB
grafana	3000	3001	Monitoring
caddy	80, 443	80, 443	Reverse proxy

Docker Network

All services communicate via vigil-net external network.

Internal hostnames:

heuristics-service (Branch A)
semantic-service (Branch B)
prompt-guard-api (Branch C)
vigil-presidio-pii or presidio-pii-api
vigil-language-detector or language-detector
vigil-clickhouse or clickhouse
vigil-n8n or n8n
web-ui-backend
web-ui-frontend

Service Dependencies (Startup Order)

                    vigil-net (network)
                          │
    ┌─────────────────────┼─────────────────────┐
    │                     │                     │
clickhouse            grafana              caddy
    │
    ├── heuristics-service
    ├── semantic-service (depends: clickhouse)
    ├── prompt-guard-api
    │
    ├── presidio-pii-api
    ├── language-detector
    │
    └── n8n (depends: all detection services)
            │
            └── web-ui-backend (depends: n8n, clickhouse)
                    │
                    └── web-ui-frontend

Common Commands

Start All Services

docker-compose up -d

Start Services by Function

# 3-Branch Detection only
docker-compose up -d heuristics-service semantic-service prompt-guard-api

# PII Detection only
docker-compose up -d presidio-pii-api language-detector

# Monitoring only
docker-compose up -d clickhouse grafana

# Web UI only
docker-compose up -d web-ui-backend web-ui-frontend caddy

# Workflow engine
docker-compose up -d n8n

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f heuristics-service

# Last 100 lines
docker-compose logs --tail=100 n8n

# Multiple services
docker-compose logs -f heuristics-service semantic-service prompt-guard-api

Restart Services

# All
docker-compose restart

# Specific
docker-compose restart heuristics-service

# 3-Branch services
docker-compose restart heuristics-service semantic-service prompt-guard-api

Stop and Remove

# Stop all
docker-compose down

# Stop and remove volumes (DESTRUCTIVE!)
docker-compose down -v

Rebuild After Changes

# Rebuild all
docker-compose up --build -d

# Rebuild specific
docker-compose up --build -d heuristics-service

# Rebuild with no cache
docker-compose build --no-cache heuristics-service

Service Health Checks

Check Running Containers

docker ps
# Should show 11 containers: vigil-*, heuristics-service, semantic-service, etc.

Test Service Endpoints

# Branch A - Heuristics
curl http://localhost:5005/health

# Branch B - Semantic
curl http://localhost:5006/health

# Branch C - LLM Guard
curl http://localhost:8000/health

# PII Detection
curl http://localhost:5001/health

# Language Detection
curl http://localhost:5002/health

# n8n
curl http://localhost:5678/healthz

# ClickHouse
curl http://localhost:8123/ping

# Grafana
curl -I http://localhost:3001

# Backend API
curl http://localhost:8787/api/files

# Proxy
curl -I http://localhost/ui/

Check All Services Script

#!/bin/bash
# scripts/health-check.sh

services=(
  "5005:Heuristics"
  "5006:Semantic"
  "8000:LLM Guard"
  "5001:Presidio"
  "5002:Language"
  "5678:n8n"
  "8123:ClickHouse"
  "3001:Grafana"
  "8787:Backend"
)

for svc in "${services[@]}"; do
  port="${svc%%:*}"
  name="${svc##*:}"
  if curl -s "http://localhost:$port/health" > /dev/null 2>&1; then
    echo "✅ $name (:$port)"
  else
    echo "❌ $name (:$port)"
  fi
done

Docker Network

Inspect Network

docker network inspect vigil-net

Create Network (if missing)

docker network create vigil-net

Test Inter-Service Connectivity

# From n8n to heuristics
docker exec vigil-n8n curl -s http://heuristics-service:5005/health

# From n8n to semantic
docker exec vigil-n8n curl -s http://semantic-service:5006/health

# From n8n to prompt-guard
docker exec vigil-n8n curl -s http://prompt-guard-api:8000/health

Volume Management

List Volumes

docker volume ls | grep vigil

Backup Volumes

# ClickHouse data
docker run --rm -v vigil_clickhouse_data:/data -v $(pwd):/backup alpine tar czf /backup/clickhouse-backup.tar.gz /data

# n8n data
docker run --rm -v vigil_n8n_data:/data -v $(pwd):/backup alpine tar czf /backup/n8n-backup.tar.gz /data

# Semantic embeddings
docker run --rm -v vigil_semantic_data:/data -v $(pwd):/backup alpine tar czf /backup/semantic-backup.tar.gz /data

Remove Volumes (DESTRUCTIVE!)

docker volume rm vigil_clickhouse_data

Troubleshooting

Port Already in Use

# Find process using port
lsof -i :5005

# Kill process (if needed)
kill -9 <PID>

Service Won't Start

# Check logs
docker-compose logs heuristics-service

# Check network
docker network inspect vigil-net

# Verify environment variables
docker-compose config

# Check dependencies
docker-compose ps

Container Crashes

# View last logs before crash
docker logs --tail=100 heuristics-service

# Check restart count
docker ps -a | grep vigil

# Inspect container
docker inspect heuristics-service

Network Issues

# Restart networking
docker-compose down
docker network rm vigil-net
docker network create vigil-net
docker-compose up -d

Branch Timeout Issues

# Check branch timing in ClickHouse
docker exec vigil-clickhouse clickhouse-client -q "
  SELECT
    avg(branch_a_timing_ms) as a_avg,
    avg(branch_b_timing_ms) as b_avg,
    avg(branch_c_timing_ms) as c_avg
  FROM n8n_logs.events_processed
  WHERE timestamp > now() - INTERVAL 1 HOUR
"

# Check service resource usage
docker stats heuristics-service semantic-service prompt-guard-api

Environment Variables

Loaded from .env file:

# ClickHouse
CLICKHOUSE_USER=admin
CLICKHOUSE_PASSWORD=<auto-generated>

# Grafana
GF_SECURITY_ADMIN_PASSWORD=<auto-generated>

# Backend
SESSION_SECRET=<auto-generated>
JWT_SECRET=<auto-generated>

# Heuristics Service
HEURISTICS_PORT=5005
HEURISTICS_TIMEOUT=1000

# Semantic Service
SEMANTIC_PORT=5006
SEMANTIC_TIMEOUT=2000
EMBEDDING_MODEL=all-MiniLM-L6-v2

# LLM Guard
PROMPT_GUARD_PORT=8000
PROMPT_GUARD_TIMEOUT=3000

Development vs Production

Development (individual services)

# Backend dev server
cd services/web-ui/backend && npm run dev

# Frontend dev server
cd services/web-ui/frontend && npm run dev

# Heuristics dev
cd services/heuristics-service && npm run dev

# Semantic dev
cd services/semantic-service && python app.py

Production (Docker)

# Build and start all
docker-compose up --build -d

# Verify all healthy
./scripts/status.sh

Monitoring Resources

Container Stats

docker stats

Disk Usage

docker system df

Prune Unused Resources

# Remove unused containers, images, networks
docker system prune

# Remove volumes too (CAREFUL!)
docker system prune -a --volumes

Related Skills

n8n-vigil-workflow - 24-node workflow service
clickhouse-grafana-monitoring - Database management
pattern-library-manager - Heuristics patterns
presidio-pii-specialist - PII detection service

References

Docker Compose: docker-compose.yml
Heuristics: services/heuristics-service/
Semantic: services/semantic-service/
Environment: .env

Version History

v2.0.0 (Current): 11 services, 3-branch architecture
v1.6.11: 9 services (no heuristics, no semantic)
v1.6.0: Added presidio-pii-api, language-detector

Install Skill

SKILL.md

Docker Orchestration for Vigil Guard v2.0.0

Overview

When to Use This Skill

Service Architecture (v2.0.0)

All Services (11 containers)

Service Ports

Docker Network

Service Dependencies (Startup Order)

Common Commands

Start All Services

Start Services by Function

View Logs

Restart Services

Stop and Remove

Rebuild After Changes

Service Health Checks

Check Running Containers

Test Service Endpoints

Check All Services Script

Docker Network

Inspect Network

Create Network (if missing)

Test Inter-Service Connectivity

Volume Management

List Volumes

Backup Volumes

Remove Volumes (DESTRUCTIVE!)

Troubleshooting

Port Already in Use

Service Won't Start

Container Crashes

Network Issues

Branch Timeout Issues

Environment Variables

Development vs Production

Development (individual services)

Production (Docker)

Monitoring Resources

Container Stats

Disk Usage

Prune Unused Resources

Related Skills

References

Version History