tractatus/deployment-quickstart/README.md

Tractatus Framework - Deployment Quickstart Kit

Deploy Tractatus in 30 minutes - Production-ready Docker deployment with all 5 governance services.

🎯 What You Get

• MongoDB 7.0 - Database for governance rules and audit logs
• Node.js Application - Web interface and API
• 5 Core Governance Services:
  • BoundaryEnforcer - Prevents automation of values decisions
  • InstructionPersistenceClassifier - Classifies and stores instructions
  • CrossReferenceValidator - Prevents pattern bias override
  • ContextPressureMonitor - Detects degraded operating conditions
  • MetacognitiveVerifier - Self-checks complex reasoning
• Sample Governance Rules - 10 example rules to get started
• Verification Script - Automated deployment testing
• Troubleshooting Guide - Common issues and solutions

---

📋 Prerequisites

Required

• Docker 20.10+ (Install Docker)
• Docker Compose 2.0+ (included with Docker Desktop)
• 2GB RAM minimum (4GB recommended)
• 10GB disk space

Recommended

• Domain name with DNS configured
• SSL certificate (Let's Encrypt recommended)
• Anthropic API key (for AI-assisted features)

Check Your System

docker --version          # Should be 20.10+
docker compose version    # Should be 2.0+

---

🚀 Quick Start (30 Minutes)

Step 1: Download and Extract (2 minutes)

# Download deployment package
wget https://agenticgovernance.digital/downloads/tractatus-quickstart.tar.gz

# Extract
tar -xzf tractatus-quickstart.tar.gz
cd tractatus-quickstart

Step 2: Configure Environment (5 minutes)

# Copy environment template
cp .env.example .env

# Edit configuration
nano .env  # or vi, emacs, code, etc.

⚠️ CRITICAL: Update these values in .env:

# Generate secure secrets:
openssl rand -base64 32  # Use for JWT_SECRET
openssl rand -base64 32  # Use for SESSION_SECRET
openssl rand -base64 32  # Use for MONGODB_PASSWORD

# Required changes:
MONGODB_PASSWORD=<paste-first-secret>
JWT_SECRET=<paste-second-secret>
SESSION_SECRET=<paste-third-secret>
ADMIN_PASSWORD=<choose-strong-password>
ADMIN_EMAIL=admin@your-domain.com
BASE_URL=https://your-domain.com
ANTHROPIC_API_KEY=sk-ant-your-key-here  # Get from console.anthropic.com

Step 3: Build and Start (10 minutes)

# Build containers
docker compose build

# Start services
docker compose up -d

# Watch logs (Ctrl+C to exit, containers keep running)
docker compose logs -f

Wait for: Server started on port 9000 and MongoDB connected successfully

Step 4: Initialize Database (3 minutes)

# Create admin account and seed initial data
docker compose exec tractatus-app node scripts/seed-admin.js
docker compose exec tractatus-app node scripts/init-db.js

# Optional: Load sample governance rules
docker compose exec tractatus-app node scripts/load-governance-rules.js sample-governance-rules.json

Step 5: Verify Deployment (5 minutes)

# Run automated verification
chmod +x verify-deployment.sh
./verify-deployment.sh

Expected output:

╔════════════════════════════════════════════════════════════════════╗
║                     Verification Results                           ║
╚════════════════════════════════════════════════════════════════════╝

  Passed:   20 tests
  Failed:   0 tests
  Warnings: 2 tests

✓ All critical tests passed! Deployment is ready.

Step 6: Access Your Deployment (5 minutes)

1. Homepage: http://localhost:9000 (or your domain)
2. Admin Panel: http://localhost:9000/admin
   • Email: (from .env)
   • Password: (from .env)
3. API Health: http://localhost:9000/api/health
4. Interactive Demos: http://localhost:9000/demos/tractatus-demo.html

---

🔧 Configuration Guide

Basic Configuration

Minimal .env for local development:

NODE_ENV=development
MONGODB_PASSWORD=dev_password_123
JWT_SECRET=dev_jwt_secret_456
SESSION_SECRET=dev_session_secret_789
ADMIN_PASSWORD=admin123
ADMIN_EMAIL=admin@localhost
ANTHROPIC_API_KEY=sk-ant-your-key

Production Configuration

Recommended .env for production:

NODE_ENV=production
BASE_URL=https://your-domain.com

# Secrets (use openssl rand -base64 32)
MONGODB_PASSWORD=<strong-random-password>
JWT_SECRET=<strong-random-secret>
SESSION_SECRET=<strong-random-secret>

# Admin
ADMIN_EMAIL=admin@your-domain.com
ADMIN_PASSWORD=<strong-password>

# API
ANTHROPIC_API_KEY=sk-ant-your-production-key

# Security
HELMET_ENABLED=true
CSP_ENABLED=true
CORS_ORIGIN=https://your-domain.com

# Performance
RATE_LIMIT_MAX_REQUESTS=100
RATE_LIMIT_WINDOW_MS=900000

# Features
BLOG_ENABLED=true
KOHA_ENABLED=true
DEMOS_ENABLED=true
ANALYTICS_ENABLED=false  # Set to true after configuring Plausible

Governance Service Configuration

Enable/disable individual services:

BOUNDARY_ENFORCER_ENABLED=true         # Blocks values decisions
CONTEXT_PRESSURE_ENABLED=true         # Monitors session degradation
CROSS_REF_VALIDATOR_ENABLED=true      # Prevents pattern bias
PERSISTENCE_CLASSIFIER_ENABLED=true   # Classifies instructions
METACOGNITIVE_VERIFIER_ENABLED=true   # Self-verification

---

📊 Governance Rules

Loading Sample Rules

The deployment includes 10 sample governance rules covering:

• Strategic: Values decisions, Te Tiriti commitments
• Operational: Classification, context pressure
• System: Database configuration, project isolation
• Security: Content Security Policy enforcement
• Quality: World-class standards

Load rules:

docker compose exec tractatus-app node scripts/load-governance-rules.js sample-governance-rules.json

Creating Custom Rules

See sample-governance-rules.json for the schema. Each rule includes:

{
  "rule_id": "CUSTOM-001",
  "quadrant": "STRATEGIC|OPERATIONAL|TACTICAL|SYSTEM|STOCHASTIC",
  "persistence": "HIGH|MEDIUM|LOW|VARIABLE",
  "title": "Rule Title",
  "content": "What the rule enforces",
  "enforced_by": "BoundaryEnforcer|CrossReferenceValidator|...",
  "violation_action": "BLOCK_AND_ESCALATE|WARN|LOG",
  "examples": ["Example 1", "Example 2"],
  "rationale": "Why this rule exists"
}

---

🧪 Testing Your Deployment

Manual Tests

1. Test Homepage:

curl http://localhost:9000/
# Should return HTML homepage

2. Test API Health:

curl http://localhost:9000/api/health
# Should return: {"status":"ok","database":"connected"}

3. Test BoundaryEnforcer:

curl -X POST http://localhost:9000/api/demo/boundary-check \
  -H "Content-Type: application/json" \
  -d '{"scenario":"privacy-decision"}'
# Should return: {"allowed":false,"reason":"Values decision requires human approval"}

4. Test Classification:

curl -X POST http://localhost:9000/api/demo/classify \
  -H "Content-Type: application/json" \
  -d '{"instruction":"Use MongoDB port 27027"}'
# Should return classification with quadrant and persistence

Automated Test Suite

# Run all tests
docker compose exec tractatus-app npm test

# Run specific test suites
docker compose exec tractatus-app npm run test:unit
docker compose exec tractatus-app npm run test:integration
docker compose exec tractatus-app npm run test:security

---

📈 Monitoring & Maintenance

View Logs

# All logs
docker compose logs -f

# Application only
docker compose logs -f tractatus-app

# MongoDB only
docker compose logs -f mongodb

# Last 100 lines
docker compose logs --tail=100 tractatus-app

Check Resource Usage

docker stats

Backup Database

# Create backup
docker exec tractatus-mongodb mongodump \
  --db tractatus_prod \
  --out /tmp/backup

# Copy backup to host
docker cp tractatus-mongodb:/tmp/backup ./mongodb-backup-$(date +%Y%m%d)

Restore Database

# Copy backup to container
docker cp ./mongodb-backup-20251012 tractatus-mongodb:/tmp/restore

# Restore
docker exec tractatus-mongodb mongorestore \
  --db tractatus_prod \
  /tmp/restore/tractatus_prod

---

🔄 Updating

Update Application Code

# Pull latest code
git pull origin main

# Rebuild containers
docker compose build

# Restart with zero downtime
docker compose up -d

Update Dependencies

# Update package.json
docker compose exec tractatus-app npm update

# Rebuild
docker compose build
docker compose up -d

---

🛑 Stopping & Restarting

Stop Services

# Stop all services (data persists)
docker compose down

# Stop and remove volumes (⚠️ destroys data)
docker compose down -v

Restart Services

# Restart all
docker compose restart

# Restart specific service
docker compose restart tractatus-app

---

🚨 Troubleshooting

See TROUBLESHOOTING.md for detailed solutions to common issues:

• Docker container won't start
• Database connection failures
• Port conflicts
• Governance services not responding
• Performance issues
• Security errors

Quick diagnostic:

./verify-deployment.sh

---

📚 Next Steps

1. Customize Governance Rules - Edit sample-governance-rules.json for your use case
2. Configure SSL - Set up HTTPS with Let's Encrypt
3. Set Up Monitoring - Configure Plausible Analytics (privacy-preserving)
4. Create Admin Users - Add team members to admin panel
5. Review Documentation - https://agenticgovernance.digital/docs
6. Join Community - Submit case studies, contribute rules

---

🤝 Support

• Documentation: https://agenticgovernance.digital/docs
• Interactive Demos: https://agenticgovernance.digital/demos
• Case Studies: https://agenticgovernance.digital/docs/case-studies
• GitHub Issues: https://github.com/AgenticGovernance/tractatus-framework/issues
• Email: research@agenticgovernance.digital

---

📄 License

Apache License 2.0 - See LICENSE file for details

---

🎯 Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     Docker Network                          │
│                                                             │
│  ┌──────────────────┐           ┌────────────────────────┐ │
│  │   MongoDB 7.0    │           │   Tractatus App        │ │
│  │   Port: 27017    │◄──────────┤   Port: 9000           │ │
│  │                  │           │                        │ │
│  │  - tractatus_prod│           │  ┌──────────────────┐  │ │
│  │  - Governance    │           │  │  5 Core Services  │  │ │
│  │    Rules         │           │  ├──────────────────┤  │ │
│  │  - Audit Logs    │           │  │ • Boundary       │  │ │
│  └──────────────────┘           │  │ • Classifier     │  │ │
│                                 │  │ • Validator      │  │ │
│                                 │  │ • Pressure       │  │ │
│                                 │  │ • Verifier       │  │ │
│                                 │  └──────────────────┘  │ │
│                                 └────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ HTTP/HTTPS
                              ▼
                         [Your Users]

---

Version: 1.0.0 Last Updated: October 12, 2025 Maintainer: Tractatus Framework Team

Ready to deploy? Run: docker compose up -d