ai-tax-agent/docs/QUICK_START.md

Quick Start - Production Deployment

Target Server: deploy@141.136.35.199
Domain: harkon.co.uk
Time Required: ~2 hours

---

🚀 Fast Track Deployment

1. Generate Secrets (5 min)

./scripts/generate-production-secrets.sh

⚠️ SAVE THE OUTPUT CREDENTIALS IN YOUR PASSWORD MANAGER!

---

2. Build & Push Images (30-60 min)

# Login to Gitea
docker login gitea.harkon.co.uk

# Build and push all images
./scripts/build-and-push-images.sh gitea.harkon.co.uk v1.0.0

---

3. Deploy Everything (15-30 min)

# Automated deployment
./scripts/deploy-to-production.sh all

Or step-by-step:

./scripts/deploy-to-production.sh backup        # Create backup
./scripts/deploy-to-production.sh prepare       # Setup directories
./scripts/deploy-to-production.sh infrastructure # Deploy infra
./scripts/deploy-to-production.sh services      # Deploy apps
./scripts/deploy-to-production.sh monitoring    # Deploy monitoring
./scripts/deploy-to-production.sh verify        # Check status

---

4. Initialize Services (20-30 min)

SSH to server:

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

Initialize Vault:

docker exec -it vault vault operator init
# ⚠️ SAVE UNSEAL KEYS!
docker exec -it vault vault operator unseal

Create MinIO Buckets:

docker exec -it minio mc alias set local http://localhost:9092 admin <MINIO_PASSWORD>
docker exec -it minio mc mb local/documents
docker exec -it minio mc mb local/models

Create NATS Streams:

docker exec -it nats nats stream add TAX_AGENT_EVENTS \
  --subjects="tax.>" --storage=file --retention=limits --max-age=7d

Configure Authentik:

1. Go to https://authentik.harkon.co.uk
2. Create groups: app-admin, app-user, app-reviewer
3. Create OAuth providers for:
   • Review UI: app.harkon.co.uk
   • Grafana: grafana.harkon.co.uk
4. Update ForwardAuth outpost

---

5. Verify (10 min)

# Check services
./scripts/deploy-to-production.sh verify

# Test endpoints
curl -I https://app.harkon.co.uk
curl -I https://api.harkon.co.uk/healthz
curl -I https://grafana.harkon.co.uk

# View logs
./scripts/deploy-to-production.sh logs svc-ingestion

---

📍 Service URLs

Public

• App: https://app.harkon.co.uk
• API: https://api.harkon.co.uk
• Grafana: https://grafana.harkon.co.uk

Admin (Auth Required)

• Vault: https://vault.harkon.co.uk
• MinIO: https://minio.harkon.co.uk
• Neo4j: https://neo4j.harkon.co.uk
• Qdrant: https://qdrant.harkon.co.uk
• Prometheus: https://prometheus.harkon.co.uk
• Loki: https://loki.harkon.co.uk
• NATS: https://nats.harkon.co.uk

---

🔧 Common Commands

View Logs

./scripts/deploy-to-production.sh logs <service-name>

Restart Service

ssh deploy@141.136.35.199
cd /opt/compose/ai-tax-agent
docker compose -f services.yaml restart svc-ingestion

Check Status

./scripts/deploy-to-production.sh verify

Update Service

# Build new image
./scripts/build-and-push-images.sh gitea.harkon.co.uk v1.0.1

# Deploy
./scripts/deploy-to-production.sh services

Backup

./scripts/deploy-to-production.sh backup

---

🆘 Troubleshooting

Service Won't Start

# Check logs
docker compose -f services.yaml logs svc-ingestion

# Check dependencies
docker compose -f infrastructure.yaml ps

# Restart
docker compose -f services.yaml restart svc-ingestion

SSL Issues

# Check Traefik logs
docker logs traefik

# Check certificates
sudo cat /opt/compose/traefik/certs/godaddy-acme.json | jq

Database Connection

# Test Postgres
docker exec -it postgres pg_isready -U postgres

# Check env vars
docker exec -it svc-ingestion env | grep POSTGRES

---

🔄 Rollback

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

# Stop services
docker compose -f services.yaml down
docker compose -f infrastructure.yaml down
docker compose -f monitoring.yaml down

# Restore backup
cd /opt/compose
tar -xzf ~/backups/backup-YYYYMMDD-HHMMSS.tar.gz

# Restart company services
cd /opt/compose/traefik && docker compose up -d
cd /opt/compose/authentik && docker compose up -d

---

📚 Full Documentation

• Deployment Plan: docs/DEPLOYMENT_PLAN.md
• Deployment Checklist: docs/DEPLOYMENT_CHECKLIST.md
• Deployment Progress: docs/DEPLOYMENT_PROGRESS.md
• Production README: infra/compose/production/README.md
• Environment Comparison: docs/ENVIRONMENT_COMPARISON.md

---

✅ Success Checklist

• Secrets generated and saved
• Images built and pushed
• Backup created
• Infrastructure deployed
• Services deployed
• Monitoring deployed
• Vault initialized
• MinIO buckets created
• NATS streams created
• Authentik configured
• All services healthy
• UI accessible
• API accessible
• Grafana accessible
• No errors in logs

---

Need Help? Check the full documentation in docs/ or review logs with:

./scripts/deploy-to-production.sh logs <service>