10 KiB
10 KiB
brew install rust\n- Nushell 0.107+: brew install nushell\n\nFor Docker Deployment:\n\n- OrbStack (recommended): https://orbstack.dev\n- Or Docker Desktop: brew install --cask docker\n\n---\n\n## 🚀 Deployment Methods\n\n### Method 1: Native Execution (Recommended for Development)\n\nFastest startup, easiest debugging, direct access to logs\n\n\ncd provisioning/platform/scripts\n\n# 1. Build all services\nnu run-native.nu build\n\n# 2. Start all services in background\nnu run-native.nu start-all --background\n\n# 3. Check status\nnu run-native.nu status\n\n# 4. View logs\nnu run-native.nu logs orchestrator --follow\n\n# 5. Stop all\nnu run-native.nu stop-all\n\n\nServices will run on:\n\n- Orchestrator: http://localhost:8080\n- Control Center: http://localhost:8081\n\nData stored in:\n\n- ~/.provisioning-platform/data/\n- ~/.provisioning-platform/logs/\n\n---\n\n### Method 2: Docker Execution (Recommended for Production-like Testing)\n\nIsolated environments, easy cleanup, supports all deployment modes\n\n\ncd provisioning/platform/scripts\n\n# 1. Build Docker images (Solo mode)\nnu run-docker.nu build solo\n\n# 2. Start services in background\nnu run-docker.nu start solo --detach\n\n# 3. Check status\nnu run-docker.nu status\n\n# 4. View logs\nnu run-docker.nu logs orchestrator --follow\n\n# 5. Stop all\nnu run-docker.nu stop\n\n\nDeployment Modes:\n\n- solo - 2 CPU / 4GB RAM (dev/test)\n- multiuser - 4 CPU / 8GB RAM (team)\n- cicd - 8 CPU / 16GB RAM (automation)\n- enterprise - 16 CPU / 32GB RAM (production + KMS)\n\n---\n\n## 📋 Complete Command Reference\n\n### Native Execution (run-native.nu)\n\n| Command | Description |\n| --------- | ------------- |\n| build | Build all services |\n| start <service> | Start orchestrator or control_center |\n| start-all | Start all services |\n| stop <service> | Stop a specific service |\n| stop-all | Stop all services |\n| status | Show service status |\n| logs <service> | Show logs (add --follow) |\n| health | Check service health |\n\nExamples:\n\n\nnu run-native.nu build\nnu run-native.nu start orchestrator --background\nnu run-native.nu start control_center --background\nnu run-native.nu logs orchestrator --follow\nnu run-native.nu health\nnu run-native.nu stop-all\n\n\n---\n\n### Docker Execution (run-docker.nu)\n\n| Command | Description |\n| --------- | ------------- |\n| build [mode] | Build Docker images |\n| start [mode] | Start services (add --detach) |\n| stop | Stop all services (add --volumes to delete data) |\n| restart [mode] | Restart services |\n| status | Show container status |\n| logs <service> | Show logs (add --follow) |\n| exec <service> <cmd> | Execute command in container |\n| stats | Show resource usage |\n| health | Check service health |\n| config [mode] | Show docker-compose config |\n| clean | Remove containers (add --all for images too) |\n\nExamples:\n\n\n# Solo mode (fastest)\nnu run-docker.nu build solo\nnu run-docker.nu start solo --detach\n\n# Enterprise mode (with KMS)\nnu run-docker.nu build enterprise\nnu run-docker.nu start enterprise --detach\n\n# Operations\nnu run-docker.nu status\nnu run-docker.nu logs control-center --follow\nnu run-docker.nu exec orchestrator bash\nnu run-docker.nu stats\nnu run-docker.nu stop\n\n\n---\n\n## 🗄️ Database Information\n\n### Control-Center Database\n\nType: SurrealDB with in-memory backend (kv-mem)\nLocation: In-memory (data persisted during container/process lifetime)\nProduction Alternative: SurrealDB with remote WebSocket connection for persistent storage\n\nNo separate database server required - SurrealDB in-memory backend is embedded in the control-center process.\n\n### Orchestrator Storage\n\nType: Filesystem queue (default)\nLocation:\n\n- Native: ~/.provisioning-platform/data/orchestrator/queue.rkvs\n- Docker: /data/queue.rkvs (inside container)\n\nProduction Option: Switch to SurrealDB via config for distributed deployments.\n\n---\n\n## ⚙️ Configuration Loading\n\nServices load configuration in this order (priority: low → high):\n\n1. System Defaults - provisioning/config/config.defaults.toml\n2. Service Defaults - provisioning/platform/{service}/config.defaults.toml\n3. Workspace Config - workspace/{name}/config/provisioning.yaml\n4. User Config - ~/Library/Application Support/provisioning/user_config.yaml\n5. Environment Variables - CONTROL_CENTER_*, ORCHESTRATOR_*\n6. Runtime Overrides - --config flag\n\nSee full documentation: docs/architecture/DATABASE_AND_CONFIG_ARCHITECTURE.md\n\n---\n\n## 🐛 Troubleshooting\n\n### Native Deployment Issues\n\nBuild fails:\n\n\n# Clean and rebuild\ncd provisioning/platform\ncargo clean\ncargo build --release\n\n\nPort already in use:\n\n\n# Check what's using the port\nlsof -i :8080\nlsof -i :8081\n\n# Kill the process or use different ports via environment variables\nexport ORCHESTRATOR_SERVER_PORT=8090\nexport CONTROL_CENTER_SERVER_PORT=8091\n\n\nService won't start:\n\n\n# Check logs for errors\nnu run-native.nu logs orchestrator\n\n# Run in foreground to see output\nnu run-native.nu start orchestrator\n\n\n---\n\n### Docker Deployment Issues\n\nBuild fails with workspace errors:\n\n- Fixed! Dockerfiles now properly handle workspace structure\n- If still failing: nu run-docker.nu build solo --no-cache\n\nContainers won't start:\n\n\n# Check container logs\nnu run-docker.nu logs orchestrator\n\n# Check Docker daemon\ndocker ps\ndocker info\n\n# Restart Docker/OrbStack\n\n\nPort conflicts:\n\n\n# Check what's using ports\nlsof -i :8080\nlsof -i :8081\n\n# Stop conflicting services or modify docker-compose.yaml ports\n\n\nOut of resources:\n\n\n# Check current usage\nnu run-docker.nu stats\n\n# Clean up unused containers/images\ndocker system prune -a\n\n# Or use the script\nnu run-docker.nu clean --all\n\n\n---\n\n## 🔐 KMS Integration (Enterprise Mode)\n\nEnterprise mode includes Cosmian KMS for production-grade secret management.\n\nStart with KMS:\n\n\nnu run-docker.nu build enterprise\nnu run-docker.nu start enterprise --detach\n\n\nAccess KMS:\n\n- KMS API: http://localhost:9998\n- KMS Health: http://localhost:9998/health\n\nKMS Features:\n\n- SSL certificate lifecycle management\n- SSH private key rotation\n- Cloud credential auto-refresh\n- Audit trails\n- Automatic key rotation\n\nSee full KMS documentation: provisioning/platform/control-center/src/kms/README.md\n\n---\n\n## 📊 Monitoring\n\n### Health Checks\n\nNative:\n\n\nnu run-native.nu health\n\n\nDocker:\n\n\nnu run-docker.nu health\n\n\nManual:\n\n\ncurl http://localhost:8080/health # Orchestrator\ncurl http://localhost:8081/health # Control Center\ncurl http://localhost:9998/health # KMS (enterprise only)\n\n\n### Resource Usage\n\nDocker:\n\n\nnu run-docker.nu stats\n\n\nNative:\n\n\nps aux | grep -E "provisioning-orchestrator|control-center"\ntop -pid <pid>\n\n\n---\n\n## 🧪 Testing Both Methods\n\n### Test Native Deployment\n\n\ncd provisioning/platform/scripts\n\n# 1. Build\nnu run-native.nu build\n\n# 2. Start services\nnu run-native.nu start-all --background\n\n# 3. Verify\nnu run-native.nu status\nnu run-native.nu health\n\n# 4. Test API\ncurl http://localhost:8080/health\ncurl http://localhost:8081/health\n\n# 5. Clean up\nnu run-native.nu stop-all\n\n\n### Test Docker Deployment\n\n\ncd provisioning/platform/scripts\n\n# 1. Build\nnu run-docker.nu build solo\n\n# 2. Start services\nnu run-docker.nu start solo --detach\n\n# 3. Verify\nnu run-docker.nu status\nnu run-docker.nu health\n\n# 4. Test API\ncurl http://localhost:8080/health\ncurl http://localhost:8081/health\n\n# 5. Clean up\nnu run-docker.nu stop --volumes\n\n\n---\n\n## 🎯 Best Practices\n\n### Development Workflow\n\n1. Use Native for Active Development\n - Faster iteration (no Docker rebuild)\n - Direct log access\n - Easy debugging with IDE\n\n2. Use Docker for Integration Testing\n - Test deployment configurations\n - Verify Docker builds\n - Simulate production environment\n\n### Production Deployment\n\n1. Use Docker/Kubernetes\n - Isolated environments\n - Easy scaling\n - Standard deployment\n\n2. Use Enterprise Mode\n - KMS for secret management\n - Full monitoring stack\n - High availability\n\n---\n\n## 📚 Related Documentation\n\n- Database Architecture: docs/architecture/DATABASE_AND_CONFIG_ARCHITECTURE.md\n- KMS Integration: provisioning/platform/control-center/src/kms/README.md\n- Configuration System: .claude/features/configuration-system.md\n- Workspace Switching: .claude/features/workspace-switching.md\n- Orchestrator Architecture: .claude/features/orchestrator-architecture.md\n\n---\n\n## ✅ Summary\n\n### Native Execution\n\n- ✅ Fixed: Workspace builds work correctly\n- ✅ Fast: No container overhead\n- ✅ Simple: Direct binary execution\n- ✅ Best for: Development, debugging\n\n### Docker Execution\n\n- ✅ Fixed: Dockerfiles now workspace-aware\n- ✅ Isolated: Clean environments\n- ✅ Flexible: Multiple deployment modes\n- ✅ Best for: Testing, production-like deployments\n\nBoth methods fully supported and tested!\n\n---\n\nQuick Links:\n\n- Native Script: provisioning/platform/scripts/run-native.nu\n- Docker Script: provisioning/platform/scripts/run-docker.nu\n- Docker Files: provisioning/platform/docker-compose.yaml + mode-specific overrides