ai-tax-agent/docs/automation-guide.md

# 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
```