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

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

# 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

make clean
make run

Authentik Issues

make restart-authentik

Database Problems

make fix-databases

Network Issues

make networks-clean
make networks