Initial commit

infra/QUICK_START.md

@@ -0,0 +1,349 @@
+# 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
+
+```bash
+cp infra/environments/local/.env.example infra/environments/local/.env
+```
+
+### 2. Setup Networks
+
+```bash
+./infra/scripts/setup-networks.sh
+```
+
+### 3. Deploy
+
+```bash
+./infra/scripts/deploy.sh local all
+```
+
+### 4. Access Services
+
+- **Grafana**: http://localhost:3000 (admin/admin)
+- **MinIO**: http://localhost:9093 (minioadmin/minioadmin)
+- **Vault**: http://localhost:8200 (token: dev-root-token)
+- **Traefik Dashboard**: http://localhost:8080
+
+### 5. Build and Run Services
+
+```bash
+# 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
+
+```bash
+ssh deploy@dev-server.harkon.co.uk
+cd /opt/ai-tax-agent
+```
+
+### 2. Create Environment File
+
+```bash
+cp infra/environments/development/.env.example infra/environments/development/.env
+```
+
+### 3. Generate Secrets
+
+```bash
+./scripts/generate-production-secrets.sh
+```
+
+### 4. Edit Environment
+
+```bash
+vim infra/environments/development/.env
+```
+
+Update:
+- `DOMAIN=dev.harkon.co.uk`
+- API keys
+- Registry credentials
+
+### 5. Deploy
+
+```bash
+./infra/scripts/setup-networks.sh
+./infra/scripts/deploy.sh development all
+```
+
+### 6. Access
+
+- https://grafana.dev.harkon.co.uk
+- https://minio.dev.harkon.co.uk
+- https://vault.dev.harkon.co.uk
+
+---
+
+## Production Server
+
+### 1. SSH to Server
+
+```bash
+ssh deploy@141.136.35.199
+cd /opt/ai-tax-agent
+```
+
+### 2. Verify Environment File
+
+```bash
+# Should already exist from previous setup
+cat infra/environments/production/.env | grep DOMAIN
+```
+
+### 3. Deploy Infrastructure
+
+```bash
+./infra/scripts/setup-networks.sh
+./infra/scripts/deploy.sh production infrastructure
+```
+
+### 4. Deploy Monitoring
+
+```bash
+./infra/scripts/deploy.sh production monitoring
+```
+
+### 5. Deploy Services
+
+```bash
+./infra/scripts/deploy.sh production services
+```
+
+### 6. Access
+
+- https://grafana.harkon.co.uk
+- https://minio.harkon.co.uk
+- https://vault.harkon.co.uk
+- https://ui-review.harkon.co.uk
+
+---
+
+## Common Commands
+
+### Deploy Specific Stack
+
+```bash
+# 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
+
+```bash
+./infra/scripts/deploy.sh production down
+```
+
+### View Logs
+
+```bash
+# 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
+
+```bash
+docker restart vault
+```
+
+### Check Status
+
+```bash
+docker ps
+```
+
+---
+
+## Troubleshooting
+
+### Services Not Starting
+
+```bash
+# Check logs
+docker compose -f infra/base/infrastructure.yaml --env-file infra/environments/production/.env logs
+
+# Check specific service
+docker logs vault
+```
+
+### Network Issues
+
+```bash
+# 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
+
+```bash
+# 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](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!**
+
+```bash
+cp infra/environments/local/.env.example infra/environments/local/.env
+./infra/scripts/setup-networks.sh
+./infra/scripts/deploy.sh local all
+```
+