QUICKSTART.md

Vigil Guard - Quick Start Guide

Get up and running in 5 minutes! ⚡

1️⃣ Prerequisites Check

Before starting, ensure you have:

# Check Node.js (need ≥18)
node --version

# Check Docker
docker --version

# Check Docker Compose
docker-compose --version

If anything is missing, install from:

• Node.js: https://nodejs.org/
• Docker: https://www.docker.com/get-started

2️⃣ One-Command Install

# Clone and install
git clone https://github.com/tbartel74/vigil-guard.git
cd vigil-guard
./install.sh

That's it! The script will:

• ✓ Verify all prerequisites
• ✓ Install dependencies
• ✓ Build projects
• ✓ Start all services
• ✓ Run health checks

Time: ~5-10 minutes (depending on internet speed)

3️⃣ Access Your Services

Once installation completes, open these URLs:

Service	URL	Credentials
🎨 Web UI	http://localhost/ui	admin/[generated by install.sh - check .env]
⚙️ n8n	http://localhost/n8n	(create on first access)
📊 Grafana	http://localhost/grafana	admin/[generated by install.sh - check .env]
🔍 ClickHouse	http://localhost:8123	admin/[generated by install.sh - check .env]

Note: All services are accessed through Caddy reverse proxy on port 80 (except ClickHouse, which is backend-only).

4️⃣ Post-Installation Setup (Manual Steps)

⚠️ REQUIRED: n8n Workflow Configuration

After installation completes, you must perform these manual steps:

Step 1: Create n8n Account

1. Open http://localhost/n8n (accessed through Caddy reverse proxy)
2. Create your n8n account (first-time setup)
3. Login to n8n interface

Step 2: Import Workflow

1. Click on "Workflows" in the left sidebar
2. Click "Add Workflow" → "Import from File"
3. Import the workflow file from:

   services/workflow/workflows/Vigil Guard v2.1.0.json
   

4. The workflow will load with all 40 nodes

Step 3: Configure ClickHouse Credentials

1. In the imported workflow, locate the "Logging to ClickHouse" node
2. Click on the node to open settings
3. Click "Create New Credential" for ClickHouse
4. Configure with these values:
   • Host: vigil-clickhouse
   • Port: 8123
   • Database: n8n_logs
   • Username: admin
   • Password: [check .env file for CLICKHOUSE_PASSWORD]
5. Click "Save"
6. Activate the workflow by clicking the toggle switch

Step 4: Reload Detection Services

1. Rebuild Presidio and the language detector so the workflow picks up the new validators:

   docker compose up -d --build presidio-pii-api language-detector n8n

2. Verify http://localhost:5001/health and http://localhost:5002/health report healthy.

Step 5: Sanity-Check PII Tests (optional)

cd services/workflow

✅ Your workflow is now ready to process requests!

5️⃣ Quick Test

Test the Web UI

1. Open http://localhost/ui
2. Login with admin and password from .env (WEB_UI_ADMIN_PASSWORD)
3. Navigate to Monitoring dashboard
4. View real-time statistics

Test n8n Workflow

1. Open http://localhost/n8n
2. Open the imported workflow
3. Click "Test Workflow" or send a chat message trigger
4. Watch it process through the pipeline

Test Monitoring

1. Open http://localhost/grafana
2. Login with admin and password from .env (GF_SECURITY_ADMIN_PASSWORD)
3. Navigate to Vigil Guard Dashboard
4. View real-time threat detection metrics

6️⃣ Security: Installation-Generated Credentials

⚠️ IMPORTANT: All passwords are auto-generated during ./install.sh and displayed ONCE during installation.

Where to find credentials:

• Displayed during installation - Terminal output from ./install.sh
• Stored in .env file - Root directory (never committed to git)

Services requiring authentication:

• Web UI (/ui): Username admin, password in .env as WEB_UI_ADMIN_PASSWORD
• Grafana (/grafana): Username admin, password in .env as GF_SECURITY_ADMIN_PASSWORD
• ClickHouse: Username admin, password in .env as CLICKHOUSE_PASSWORD
• n8n (/n8n): Create account on first access (your choice)

For Production Deployment:

1. ✅ Passwords already unique (32+ characters, cryptographically secure)
2. ✅ Change Web UI password: Settings → Change Password
3. ✅ Rotate other secrets: Delete .env, re-run ./install.sh
4. ✅ Document passwords in secure password manager
5. ✅ Never commit .env to version control

📖 Complete security guide: docs/SECURITY.md

7️⃣ Caddy Reverse Proxy Architecture

All services are accessed through Caddy on port 80:

Service	Direct Port	Caddy URL	Purpose
Web UI	:5173 (dev), :80 (prod)	http://localhost/ui	Configuration interface
n8n	:5678	http://localhost/n8n	Workflow editor
Grafana	:3001	http://localhost/grafana	Analytics dashboard
ClickHouse	:8123	(no proxy)	Database (backend only)

Why Caddy?

• ✅ Single entry point (port 80)
• ✅ Automatic path routing (/ui → Web UI, /n8n → n8n)
• ✅ Production-ready (HTTPS support when configured)
• ✅ Clean URLs (no port numbers)

Development Mode:

./scripts/dev.sh  # Frontend on :5173 (Vite), bypasses Caddy

Production Mode:

docker-compose up -d  # All through Caddy on :80

8️⃣ Common Commands

# Check if everything is running
./scripts/status.sh

# View logs
./scripts/logs.sh

# Restart a service
./scripts/restart.sh gui

# Stop everything
./scripts/stop.sh

# Development mode (hot reload)
./scripts/dev.sh

🐛 Troubleshooting

Services not starting?

# Check what's wrong
./scripts/status.sh
./scripts/logs.sh all

# Try restarting
./scripts/restart.sh all

Port already in use?

# Check which ports are in use
lsof -i :80    # Caddy reverse proxy (main entry point)
lsof -i :5173  # GUI Frontend (dev mode only)
lsof -i :8787  # GUI Backend
lsof -i :5678  # n8n (proxied via Caddy)
lsof -i :3001  # Grafana (proxied via Caddy)

Fresh start needed?

# Complete cleanup and reinstall
./scripts/uninstall.sh
./install.sh

📚 Next Steps

1. ✅ Complete n8n Setup (REQUIRED - see Step 4 above)

   • Create n8n account
   • Import workflow from services/workflow/workflows/Vigil Guard v2.1.0.json
   • Configure ClickHouse credentials (admin/[password from .env])

2. Configure Security Rules

   • Open Web UI at http://localhost/ui
   • Login with admin and password from .env
   • Navigate to Configuration
   • Adjust detection thresholds

3. Monitor System & New v1.8.1 Features

   • View real-time stats in Web UI Monitoring dashboard
   • Open Grafana at http://localhost/grafana for detailed analytics
   • Check Investigation Panel for PII classification tracking
   • Monitor browser fingerprinting (clientId + metadata)
   • Monitor workflow execution in n8n

4. Read Documentation

   • Installation Guide
   • Configuration Reference
   • Authentication Guide
   • API Documentation

🆘 Need Help?

• Documentation: docs/README.md
• Scripts Guide: scripts/README.md
• Architecture: docs/ARCHITECTURE.md
• Issues: GitHub Issues

🔟 Development Mode

For active development with hot reload:

./scripts/dev.sh

This will:

• Start Docker services (monitoring, n8n, databases)
• Run frontend with Vite on :5173 (hot reload, bypasses Caddy)
• Run backend with tsx watch (auto-restart)
• Open in separate terminal windows

Note: In dev mode, access Web UI at http://localhost:5173/ui (direct Vite server) In production: Access via http://localhost/ui (through Caddy proxy)

---

That's all you need to get started! 🚀

For detailed documentation, see README.md and docs/

---

Document Version: 2.1.0 Last Updated: 2025-12-14 Installation Script: install.sh v2.1.0