ai-tax-agent/infra/QUICK_START.md

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