16 KiB
16 KiB
bash\n docker --version\n # Docker version 20.10.0 or higher\n \n\n2. Docker Compose (version 2.0+)\n\n bash\n docker-compose --version\n # Docker Compose version 2.0.0 or higher\n \n\n3. Nushell (version 0.107.1+ for automation scripts)\n\n bash\n nu --version\n # 0.107.1 or higher\n \n\n### System Requirements\n\n#### Solo Mode\n\n- CPU: 2 cores\n- Memory: 4GB RAM\n- Disk: 20GB free space\n- Network: Internet connection for pulling images\n\n#### Multi-User Mode\n\n- CPU: 4 cores\n- Memory: 8GB RAM\n- Disk: 50GB free space\n- Network: Internet connection + internal network\n\n#### CI/CD Mode\n\n- CPU: 8 cores\n- Memory: 16GB RAM\n- Disk: 100GB free space\n- Network: Internet + dedicated CI/CD network\n\n#### Enterprise Mode\n\n- CPU: 16 cores\n- Memory: 32GB RAM\n- Disk: 500GB free space (SSD recommended)\n- Network: High-bandwidth, low-latency network\n\n### Optional Tools\n\n- OpenSSL (for generating secrets)\n- kubectl (for Kubernetes deployment)\n- Helm (for Kubernetes package management)\n\n---\n\n## Deployment Modes\n\n### Solo Mode\n\nUse Case: Local development, testing, personal use\n\nFeatures:\n\n- Minimal resource usage\n- No authentication required\n- SQLite databases\n- Local file storage\n\nLimitations:\n\n- Single user only\n- No version control integration\n- No audit logging\n\n### Multi-User Mode\n\nUse Case: Small team collaboration\n\nFeatures:\n\n- Multi-user authentication\n- Gitea for source control\n- PostgreSQL shared database\n- User management\n\nLimitations:\n\n- No automated pipelines\n- No advanced monitoring\n\n### CI/CD Mode\n\nUse Case: Automated deployment pipelines\n\nFeatures:\n\n- All Multi-User features\n- Provisioning API Server\n- Webhook support\n- Jenkins/GitLab Runner integration\n\nLimitations:\n\n- Basic monitoring only\n\n### Enterprise Mode\n\nUse Case: Production deployments, compliance requirements\n\nFeatures:\n\n- All CI/CD features\n- Harbor registry (enterprise OCI)\n- Cosmian KMS (secret management)\n- Full monitoring stack (Prometheus, Grafana)\n- Log aggregation (Loki, Elasticsearch)\n- Audit logging\n- TLS/SSL encryption\n- Nginx reverse proxy\n\n---\n\n## Quick Start\n\n### 1. Clone Repository\n\n{$detected_lang}\ncd /opt\ngit clone https://github.com/your-org/project-provisioning.git\ncd project-provisioning/provisioning/platform\n\n\n### 2. Generate Secrets\n\n{$detected_lang}\n# Generate .env file with random secrets\n./scripts/generate-secrets.nu\n\n# Or copy and edit manually\ncp .env.example .env\nnano .env\n\n\n### 3. Choose Deployment Mode and Deploy\n\n#### Solo Mode\n\n{$detected_lang}\n./scripts/deploy-platform.nu --mode solo\n\n\n#### Multi-User Mode\n\n{$detected_lang}\n# Generate secrets first\n./scripts/generate-secrets.nu\n\n# Deploy\n./scripts/deploy-platform.nu --mode multi-user\n\n\n#### CI/CD Mode\n\n{$detected_lang}\n./scripts/deploy-platform.nu --mode cicd --build\n\n\n#### Enterprise Mode\n\n{$detected_lang}\n# Full production deployment\n./scripts/deploy-platform.nu --mode enterprise --build --wait 600\n\n\n### 4. Verify Deployment\n\n{$detected_lang}\n# Check all services\n./scripts/health-check.nu\n\n# View logs\ndocker-compose logs -f\n\n\n### 5. Access Services\n\n- Orchestrator: http://localhost:9090\n- Control Center: http://localhost:8081\n- OCI Registry: http://localhost:5000\n- Gitea (Multi-User+): http://localhost:3000\n- Grafana (Enterprise): http://localhost:3001\n\n---\n\n## Configuration\n\n### Environment Variables\n\nThe .env file controls all deployment settings. Key variables:\n\n#### Platform Configuration\n\n{$detected_lang}\nPROVISIONING_MODE=solo # solo, multi-user, cicd, enterprise\nPLATFORM_ENVIRONMENT=development # development, staging, production\n\n\n#### Service Ports\n\n{$detected_lang}\nORCHESTRATOR_PORT=8080\nCONTROL_CENTER_PORT=8081\nGITEA_HTTP_PORT=3000\nOCI_REGISTRY_PORT=5000\n\n\n#### Security Settings\n\n{$detected_lang}\n# Generate with: openssl rand -base64 32\nCONTROL_CENTER_JWT_SECRET=<random-secret>\nAPI_SERVER_JWT_SECRET=<random-secret>\nPOSTGRES_PASSWORD=<random-password>\n\n\n#### Resource Limits\n\n{$detected_lang}\nORCHESTRATOR_CPU_LIMIT=2000m\nORCHESTRATOR_MEMORY_LIMIT=2048M\n\n\n### Configuration Files\n\n#### Docker Compose\n\n- Main: docker-compose.yaml (base services)\n- Solo: infrastructure/docker/docker-compose.solo.yaml\n- Multi-User: infrastructure/docker/docker-compose.multi-user.yaml\n- CI/CD: infrastructure/docker/docker-compose.cicd.yaml\n- Enterprise: infrastructure/docker/docker-compose.enterprise.yaml\n\n#### Service Configurations\n\n- Orchestrator: orchestrator/config.defaults.toml\n- Control Center: control-center/config.defaults.toml\n- CoreDNS: config/coredns/Corefile\n- OCI Registry: infrastructure/oci-registry/config.json\n- Nginx: infrastructure/nginx/nginx.conf\n- Prometheus: infrastructure/monitoring/prometheus/prometheus.yml\n\n---\n\n## Deployment Methods\n\n### Method 1: Docker Compose (Recommended)\n\n#### Deploy\n\n{$detected_lang}\n# Solo mode\ndocker-compose -f docker-compose.yaml \\n -f infrastructure/docker/docker-compose.solo.yaml \\n up -d\n\n# Multi-user mode\ndocker-compose -f docker-compose.yaml \\n -f infrastructure/docker/docker-compose.multi-user.yaml \\n up -d\n\n# CI/CD mode\ndocker-compose -f docker-compose.yaml \\n -f infrastructure/docker/docker-compose.multi-user.yaml \\n -f infrastructure/docker/docker-compose.cicd.yaml \\n up -d\n\n# Enterprise mode\ndocker-compose -f docker-compose.yaml \\n -f infrastructure/docker/docker-compose.multi-user.yaml \\n -f infrastructure/docker/docker-compose.cicd.yaml \\n -f infrastructure/docker/docker-compose.enterprise.yaml \\n up -d\n\n\n#### Manage Services\n\n{$detected_lang}\n# View logs\ndocker-compose logs -f [service-name]\n\n# Restart service\ndocker-compose restart orchestrator\n\n# Stop all services\ndocker-compose down\n\n# Stop and remove volumes (WARNING: data loss)\ndocker-compose down --volumes\n\n\n### Method 2: Systemd (Linux Production)\n\n#### Install Services\n\n{$detected_lang}\ncd systemd\nsudo ./install-services.sh\n\n\n#### Manage via systemd\n\n{$detected_lang}\n# Start platform\nsudo systemctl start provisioning-platform\n\n# Enable auto-start on boot\nsudo systemctl enable provisioning-platform\n\n# Check status\nsudo systemctl status provisioning-platform\n\n# View logs\nsudo journalctl -u provisioning-platform -f\n\n# Restart\nsudo systemctl restart provisioning-platform\n\n# Stop\nsudo systemctl stop provisioning-platform\n\n\n### Method 3: Kubernetes\n\nSee KUBERNETES_DEPLOYMENT.md for detailed instructions.\n\n#### Quick Deploy\n\n{$detected_lang}\n# Create namespace\nkubectl apply -f k8s/base/namespace.yaml\n\n# Deploy services\nkubectl apply -f k8s/deployments/\nkubectl apply -f k8s/services/\nkubectl apply -f k8s/ingress/\n\n# Check status\nkubectl get pods -n provisioning\n\n\n### Method 4: Automation Script (Nushell)\n\n{$detected_lang}\n# Deploy with options\n./scripts/deploy-platform.nu --mode enterprise \\n --build \\n --wait 300\n\n# Health check\n./scripts/health-check.nu\n\n# Dry run (show what would be deployed)\n./scripts/deploy-platform.nu --mode enterprise --dry-run\n\n\n---\n\n## Post-Deployment\n\n### 1. Verify Services\n\n{$detected_lang}\n# Quick health check\n./scripts/health-check.nu\n\n# Detailed Docker status\ndocker-compose ps\n\n# Check individual service\ncurl http://localhost:9090/health\n\n\n### 2. Initial Configuration\n\n#### Create Admin User (Multi-User+)\n\nAccess Gitea at http://localhost:3000 and complete setup wizard.\n\n#### Configure DNS (Optional)\n\nAdd to /etc/hosts or configure local DNS:\n\n{$detected_lang}\n127.0.0.1 provisioning.local\n127.0.0.1 gitea.provisioning.local\n127.0.0.1 grafana.provisioning.local\n\n\n#### Configure Monitoring (Enterprise)\n\n1. Access Grafana: http://localhost:3001\n2. Login with credentials from .env:\n - Username: admin\n - Password: ${GRAFANA_ADMIN_PASSWORD}\n3. Dashboards are auto-provisioned from infrastructure/monitoring/grafana/dashboards/\n\n### 3. Load Extensions\n\n{$detected_lang}\n# List available extensions\ncurl http://localhost:8082/api/v1/extensions\n\n# Upload extension (example)\ncurl -X POST http://localhost:8082/api/v1/extensions/upload \\n -F "file=@my-extension.tar.gz"\n\n\n### 4. Test Workflows\n\n{$detected_lang}\n# Create test server (via orchestrator API)\ncurl -X POST http://localhost:9090/workflows/servers/create \\n -H "Content-Type: application/json" \\n -d '{"name": "test-server", "plan": "1xCPU-2GB"}'\n\n# Check workflow status\ncurl http://localhost:9090/tasks/<task-id>\n\n\n---\n\n## Troubleshooting\n\n### Common Issues\n\n#### Services Not Starting\n\nSymptom: docker-compose up fails or services crash\n\nSolutions:\n\n1. Check Docker daemon:\n\n bash\n systemctl status docker\n \n\n1. Check logs:\n\n bash\n docker-compose logs orchestrator\n \n\n2. Check resource limits:\n\n bash\n docker stats\n \n\n3. Increase Docker resources in Docker Desktop settings\n\n#### Port Conflicts\n\nSymptom: Error: port is already allocated\n\nSolutions:\n\n1. Find conflicting process:\n\n bash\n lsof -i :9090\n \n\n2. Change port in .env:\n\n bash\n ORCHESTRATOR_PORT=9080\n \n\n3. Restart deployment:\n\n bash\n docker-compose down\n docker-compose up -d\n \n\n#### Health Checks Failing\n\nSymptom: Health check script reports unhealthy services\n\nSolutions:\n\n1. Check service logs:\n\n bash\n docker-compose logs -f <service>\n \n\n2. Verify network connectivity:\n\n bash\n docker network inspect provisioning-net\n \n\n3. Check firewall rules:\n\n bash\n sudo ufw status\n \n\n4. Wait longer for services to start:\n\n bash\n ./scripts/deploy-platform.nu --wait 600\n \n\n#### Database Connection Errors\n\nSymptom: PostgreSQL connection refused\n\nSolutions:\n\n1. Check PostgreSQL health:\n\n bash\n docker exec provisioning-postgres pg_isready\n \n\n2. Verify credentials in .env:\n\n bash\n grep POSTGRES_ .env\n \n\n3. Check PostgreSQL logs:\n\n bash\n docker-compose logs postgres\n \n\n4. Recreate database:\n\n bash\n docker-compose down\n docker volume rm provisioning_postgres-data\n docker-compose up -d\n \n\n#### Out of Disk Space\n\nSymptom: No space left on device\n\nSolutions:\n\n1. Clean Docker volumes:\n\n bash\n docker volume prune\n \n\n2. Clean Docker images:\n\n bash\n docker image prune -a\n \n\n3. Check volume sizes:\n\n bash\n docker system df -v\n \n\n### Getting Help\n\n- Logs: Always check logs first: docker-compose logs -f\n- Health: Run health check: ./scripts/health-check.nu --json\n- Documentation: See docs/ directory\n- Issues: File bug reports at GitHub repository\n\n---\n\n## Security Best Practices\n\n### 1. Secret Management\n\n- Never commit .env files to version control\n- Use ./scripts/generate-secrets.nu to generate strong secrets\n- Rotate secrets regularly\n- Use KMS in enterprise mode\n\n### 2. Network Security\n\n- Use TLS/SSL in production (enterprise mode)\n- Configure firewall rules:\n\n bash\n sudo ufw allow 80/tcp\n sudo ufw allow 443/tcp\n sudo ufw enable\n \n\n- Use private networks for backend services\n\n### 3. Access Control\n\n- Enable authentication in multi-user mode\n- Use strong passwords (16+ characters)\n- Configure API keys for CI/CD access\n- Enable audit logging in enterprise mode\n\n### 4. Regular Updates\n\n{$detected_lang}\n# Pull latest images\ndocker-compose pull\n\n# Rebuild with updates\n./scripts/deploy-platform.nu --pull --build\n\n\n---\n\n## Backup and Recovery\n\n### Backup\n\n{$detected_lang}\n# Backup volumes\ndocker run --rm -v provisioning_orchestrator-data:/data \\n -v $(pwd)/backup:/backup \\n alpine tar czf /backup/orchestrator-data.tar.gz -C /data .\n\n# Backup PostgreSQL\ndocker exec provisioning-postgres pg_dumpall -U provisioning > backup/postgres-backup.sql\n\n\n### Restore\n\n{$detected_lang}\n# Restore volume\ndocker run --rm -v provisioning_orchestrator-data:/data \\n -v $(pwd)/backup:/backup \\n alpine tar xzf /backup/orchestrator-data.tar.gz -C /data\n\n# Restore PostgreSQL\ndocker exec -i provisioning-postgres psql -U provisioning < backup/postgres-backup.sql\n\n\n---\n\n## Maintenance\n\n### Updates\n\n{$detected_lang}\n# Pull latest images\ndocker-compose pull\n\n# Recreate containers\ndocker-compose up -d --force-recreate\n\n# Remove old images\ndocker image prune\n\n\n### Monitoring\n\n- Prometheus: http://localhost:9090\n- Grafana: http://localhost:3001\n- Logs: docker-compose logs -f\n\n### Health Checks\n\n{$detected_lang}\n# Automated health check\n./scripts/health-check.nu\n\n# Manual checks\ncurl http://localhost:9090/health\ncurl http://localhost:8081/health\n\n\n---\n\n## Next Steps\n\n- Production Deployment Guide\n- Kubernetes Deployment Guide\n- Docker Compose Reference\n- Monitoring Setup\n- Security Hardening\n\n---\n\nDocumentation Version: 1.0.0\nLast Updated: 2025-10-06\nMaintained By: Platform Team