harkon/ai-tax-agent
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b324ff09effe98752d7fe4f0be00326c717ef1c5
ai-tax-agent/infra/QUICK_START.md
harkon b324ff09ef
Some checks failed
CI/CD Pipeline / Code Quality & Linting (push) Has been cancelled
Details
CI/CD Pipeline / Policy Validation (push) Has been cancelled
Details
CI/CD Pipeline / Test Suite (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-coverage) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-extract) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-firm-connectors) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-forms) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-hmrc) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-ingestion) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-kg) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-normalize-map) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-ocr) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-rag-indexer) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-rag-retriever) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-reason) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-rpa) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (ui-review) (push) Has been cancelled
Details
CI/CD Pipeline / Security Scanning (svc-coverage) (push) Has been cancelled
Details
CI/CD Pipeline / Security Scanning (svc-extract) (push) Has been cancelled
Details
CI/CD Pipeline / Security Scanning (svc-kg) (push) Has been cancelled
Details
CI/CD Pipeline / Security Scanning (svc-rag-retriever) (push) Has been cancelled
Details
CI/CD Pipeline / Security Scanning (ui-review) (push) Has been cancelled
Details
CI/CD Pipeline / Generate SBOM (push) Has been cancelled
Details
CI/CD Pipeline / Deploy to Staging (push) Has been cancelled
Details
CI/CD Pipeline / Deploy to Production (push) Has been cancelled
Details
CI/CD Pipeline / Notifications (push) Has been cancelled
Details
Initial commit
2025-10-11 08:41:36 +01:00

8.2 KiB
Raw Blame History

Quick Start Guide

Get AI Tax Agent infrastructure running in 5 minutes!

Prerequisites

  • Docker 24.0+ with Compose V2
  • Git
  • 10GB free disk space

Local Development (Fastest)

1. Create Environment File

cp infra/environments/local/.env.example infra/environments/local/.env

2. Setup Networks

./infra/scripts/setup-networks.sh

3. Deploy

./infra/scripts/deploy.sh local all

4. Access Services

5. Build and Run Services

# Build images
./scripts/build-and-push-images.sh localhost:5000 latest local

# Services will auto-start via deploy script

Development Server

1. SSH to Server

ssh deploy@dev-server.harkon.co.uk
cd /opt/ai-tax-agent

2. Create Environment File

cp infra/environments/development/.env.example infra/environments/development/.env

3. Generate Secrets

./scripts/generate-production-secrets.sh

4. Edit Environment

vim infra/environments/development/.env

Update:

  • DOMAIN=dev.harkon.co.uk
  • API keys
  • Registry credentials

5. Deploy

./infra/scripts/setup-networks.sh
./infra/scripts/deploy.sh development all

6. Access

Production Server

1. SSH to Server

ssh deploy@141.136.35.199
cd /opt/ai-tax-agent

2. Verify Environment File

# Should already exist from previous setup
cat infra/environments/production/.env | grep DOMAIN

3. Deploy Infrastructure

./infra/scripts/setup-networks.sh
./infra/scripts/deploy.sh production infrastructure

4. Deploy Monitoring

./infra/scripts/deploy.sh production monitoring

5. Deploy Services

./infra/scripts/deploy.sh production services

6. Access

Common Commands

Deploy Specific Stack

# Infrastructure only
./infra/scripts/deploy.sh production infrastructure

# Monitoring only
./infra/scripts/deploy.sh production monitoring

# Services only
./infra/scripts/deploy.sh production services

Stop Services

./infra/scripts/deploy.sh production down

View Logs

# All services
docker compose -f infra/base/infrastructure.yaml --env-file infra/environments/production/.env logs -f

# Specific service
docker logs -f vault

Restart Service

docker restart vault

Check Status

docker ps

Troubleshooting

Services Not Starting

# Check logs
docker compose -f infra/base/infrastructure.yaml --env-file infra/environments/production/.env logs

# Check specific service
docker logs vault

Network Issues

# Verify networks exist
docker network ls | grep -E "frontend|backend"

# Recreate networks
docker network rm frontend backend
./infra/scripts/setup-networks.sh

Environment Variables Not Loading

# Verify .env file exists
ls -la infra/environments/production/.env

# Check variables
cat infra/environments/production/.env | grep DOMAIN

Next Steps

  1. ✅ Infrastructure running
  2. 📖 Read DEPLOYMENT_GUIDE.md for detailed instructions
  3. 🔧 Configure Authentik OAuth providers
  4. 🚀 Deploy application services
  5. 📊 Setup Grafana dashboards
  6. 🔐 Initialize Vault secrets

Support

  • Documentation: See infra/README.md
  • Deployment Guide: See infra/DEPLOYMENT_GUIDE.md
  • Migration Guide: See infra/MIGRATION_GUIDE.md
  • Structure Overview: See infra/STRUCTURE_OVERVIEW.md

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                         Traefik                              │
│                    (Reverse Proxy)                           │
└─────────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
┌───────▼────────┐  ┌──────▼──────┐  ┌────────▼────────┐
│   Authentik    │  │  Monitoring  │  │   Application   │
│     (SSO)      │  │   (Grafana)  │  │    Services     │
└────────────────┘  └──────────────┘  └─────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
┌───────▼────────┐  ┌──────▼──────┐  ┌────────▼────────┐
│   PostgreSQL   │  │    Neo4j     │  │     Qdrant      │
└────────────────┘  └──────────────┘  └─────────────────┘
        │                   │                   │
┌───────▼────────┐  ┌──────▼──────┐  ┌────────▼────────┐
│     MinIO      │  │    Redis     │  │      NATS       │
└────────────────┘  └──────────────┘  └─────────────────┘

Environment Comparison

Feature Local Development Production
Domain localhost dev.harkon.co.uk harkon.co.uk
SSL Self-signed Let's Encrypt Let's Encrypt
Auth Optional Authentik Authentik
Passwords Simple Strong Strong
Monitoring Optional Full Full
Backups No Daily Daily

Service Ports (Local)

Service Port URL
Traefik Dashboard 8080 http://localhost:8080
Grafana 3000 http://localhost:3000
MinIO Console 9093 http://localhost:9093
Vault 8200 http://localhost:8200
PostgreSQL 5432 localhost:5432
Neo4j 7474 http://localhost:7474
Redis 6379 localhost:6379
Qdrant 6333 http://localhost:6333

Deployment Checklist

Before Deployment

  • Environment file created
  • Secrets generated (dev/prod)
  • Docker networks created
  • DNS configured (dev/prod)
  • GoDaddy API credentials set (dev/prod)
  • Gitea registry configured (dev/prod)

After Deployment

  • All services running (docker ps)
  • Services accessible via URLs
  • Grafana dashboards loaded
  • Vault initialized
  • MinIO buckets created
  • Authentik configured (dev/prod)
  • Monitoring alerts configured

Quick Reference

Environment Files

  • Local: infra/environments/local/.env
  • Development: infra/environments/development/.env
  • Production: infra/environments/production/.env

Compose Files

  • Infrastructure: infra/base/infrastructure.yaml
  • Services: infra/base/services.yaml
  • Monitoring: infra/base/monitoring.yaml
  • External: infra/base/external.yaml

Scripts

  • Deploy: ./infra/scripts/deploy.sh <env> <stack>
  • Setup Networks: ./infra/scripts/setup-networks.sh
  • Reorganize: ./infra/scripts/reorganize-structure.sh

Ready to deploy? Start with local development!

cp infra/environments/local/.env.example infra/environments/local/.env
./infra/scripts/setup-networks.sh
./infra/scripts/deploy.sh local all