Initial commit

docs/automation-guide.md

@@ -0,0 +1,211 @@
+# AI Tax Agent - Automation Guide
+
+This document describes the comprehensive automation system for deploying and managing the AI Tax Agent infrastructure.
+
+## 🚀 Quick Start
+
+```bash
+# Complete automated deployment
+make run
+
+# Access services
+# - Traefik Dashboard: http://localhost:8080
+# - Authentik SSO: https://auth.local
+# - Grafana: https://grafana.local
+```
+
+## 📋 Automation Scripts
+
+### Core Deployment Scripts
+
+| Script | Purpose | Usage |
+|--------|---------|-------|
+| `scripts/deploy-with-fixes.sh` | Complete deployment with all fixes | `make run` |
+| `scripts/fix-database-issues.sh` | Fix database connectivity issues | `make fix-databases` |
+| `scripts/troubleshoot.sh` | Comprehensive troubleshooting | `make troubleshoot` |
+| `scripts/create-networks.sh` | Create Docker networks | `make networks` |
+| `scripts/generate-dev-certs.sh` | Generate TLS certificates | Auto-called |
+| `scripts/verify-infra.sh` | Verify all endpoints | `make verify` |
+
+### Makefile Targets
+
+#### Primary Commands
+- `make run` - Complete automated deployment with fixes
+- `make bootstrap` - Initialize development environment
+- `make troubleshoot` - Run comprehensive diagnostics and fixes
+- `make verify` - Verify all service endpoints
+
+#### Infrastructure Management
+- `make deploy-infra` - Deploy infrastructure services only
+- `make deploy-services` - Deploy application services only
+- `make fix-databases` - Fix database connectivity issues
+- `make restart-authentik` - Restart Authentik components properly
+- `make restart-unleash` - Restart Unleash with database fixes
+
+#### Monitoring & Debugging
+- `make status` - Show container status
+- `make health` - Check service health
+- `make logs` - View all service logs
+- `make logs-service SERVICE=name` - View specific service logs
+
+## 🔧 Automated Fixes
+
+The automation system handles these common issues:
+
+### Database Issues
+- **Authentik Password Reset**: Automatically resets authentik user password
+- **Database Creation**: Creates missing databases (unleash, authentik)
+- **Connection Verification**: Ensures databases are ready before service startup
+
+### Service Ordering
+- **Dependency Management**: Starts services in correct order
+- **Health Monitoring**: Waits for services to be healthy
+- **Retry Logic**: Automatically retries failed operations
+
+### Network & Security
+- **Docker Networks**: Creates required frontend/backend networks
+- **TLS Certificates**: Generates self-signed certificates for HTTPS
+- **Host Configuration**: Sets up local domain resolution
+
+### Authentik SSO
+- **Component Ordering**: Starts Authentik services in correct sequence
+- **Database Connectivity**: Ensures proper database connection
+- **Health Verification**: Monitors Authentik health status
+
+## 🐛 Troubleshooting Automation
+
+### Automatic Diagnostics
+
+The `make troubleshoot` command performs:
+
+1. **Network Verification**: Checks Docker networks exist
+2. **Container Status**: Verifies all containers are running
+3. **Health Checks**: Monitors container health status
+4. **Endpoint Testing**: Tests all service endpoints
+5. **Common Issues**: Checks for typical configuration problems
+
+### Automatic Fixes
+
+When issues are detected, the system automatically:
+
+1. **Recreates Networks**: If Docker networks are missing
+2. **Restarts Services**: If containers are unhealthy
+3. **Fixes Databases**: If database connectivity fails
+4. **Regenerates Certificates**: If TLS certificates are missing
+
+## 📊 Monitoring Integration
+
+### Health Checks
+- Container health monitoring
+- Endpoint availability testing
+- Database connectivity verification
+- Service dependency validation
+
+### Logging
+- Centralized log collection
+- Service-specific log filtering
+- Error pattern detection
+- Performance monitoring
+
+## 🔄 Deployment Workflow
+
+### Standard Deployment (`make run`)
+
+1. **Network Setup**: Create Docker networks
+2. **Certificate Generation**: Generate TLS certificates
+3. **Core Infrastructure**: Start Traefik, PostgreSQL, Redis
+4. **Database Fixes**: Apply database connectivity fixes
+5. **Authentik Deployment**: Start Authentik components in order
+6. **Infrastructure Services**: Start remaining infrastructure
+7. **Health Verification**: Wait for Authentik to be healthy
+8. **Application Services**: Start all microservices
+9. **Final Verification**: Run endpoint tests
+
+### Infrastructure Only (`make deploy-infra`)
+
+1. **Network Setup**: Create Docker networks
+2. **Certificate Generation**: Generate TLS certificates
+3. **Database Services**: Start PostgreSQL, Redis, Authentik DB
+4. **Database Fixes**: Apply connectivity fixes
+5. **Infrastructure**: Start all infrastructure services
+6. **Health Monitoring**: Wait for services to be ready
+
+## 🛠️ Customization
+
+### Environment Variables
+
+Key variables in `infra/compose/.env`:
+
+```bash
+# Database Configuration
+POSTGRES_PASSWORD=postgres
+AUTHENTIK_DB_PASSWORD=authentik
+
+# Authentik Configuration
+AUTHENTIK_SECRET_KEY=changeme
+
+# Unleash Configuration
+UNLEASH_ADMIN_TOKEN=*:*.unleash-insecure-admin-api-token
+
+# Domain Configuration
+DOMAIN=local
+```
+
+### Service Configuration
+
+Modify `infra/compose/docker-compose.local.yml` for:
+- Service dependencies
+- Health check configurations
+- Network assignments
+- Volume mounts
+
+## 🔍 Verification
+
+### Endpoint Testing
+
+The automation verifies these endpoints:
+
+- **Traefik**: http://localhost:8080/dashboard/
+- **Authentik**: https://auth.local
+- **Grafana**: https://grafana.local
+- **Protected Services**: Redirect to Authentik
+
+### Health Monitoring
+
+Continuous monitoring of:
+- Container health status
+- Database connectivity
+- Service availability
+- Network connectivity
+
+## 📚 Best Practices
+
+1. **Always use `make run`** for initial deployment
+2. **Run `make troubleshoot`** if issues occur
+3. **Use `make verify`** to test endpoints
+4. **Check `make status`** for container health
+5. **Use `make logs-service`** for specific debugging
+
+## 🚨 Emergency Procedures
+
+### Complete Reset
+```bash
+make clean
+make run
+```
+
+### Authentik Issues
+```bash
+make restart-authentik
+```
+
+### Database Problems
+```bash
+make fix-databases
+```
+
+### Network Issues
+```bash
+make networks-clean
+make networks
+```