ai-tax-agent/docs/UI Deployment Guide.md

Deployment Guide

This document provides instructions for deploying the Tax Agent Platform UI in various environments.

Prerequisites

• Docker and Docker Compose
• Node.js 20+ (for local development)
• Access to the backend API services
• Traefik reverse proxy with Authentik authentication (for production)

Environment Variables

Create a .env file based on .env.example:

# API Configuration
NEXT_PUBLIC_API_BASE_URL=https://api.tax-agent.local
NEXT_PUBLIC_APP_ENV=production

# Application Configuration
NEXT_PUBLIC_APP_BASE=https://ui.tax-agent.local

Docker Deployment

1. Build the Docker Image

docker build -t tax-agent-ui:latest .

2. Run with Docker Compose

docker-compose up -d

3. Verify Deployment

# Check container status
docker-compose ps

# Check logs
docker-compose logs -f ui-review

# Test health endpoint
curl http://localhost:3000/api/health

Production Deployment

1. Traefik Configuration

Ensure your Traefik configuration includes:

# traefik.yml
http:
  middlewares:
    auth:
      forwardAuth:
        address: "http://authentik:9000/outpost.goauthentik.io/auth/traefik"
        trustForwardHeader: true
        authResponseHeaders:
          - X-Authenticated-User
          - X-Authenticated-Email
          - X-Authenticated-Groups

2. Docker Compose for Production

version: '3.8'

services:
  ui-review:
    image: tax-agent-ui:latest
    environment:
      - NODE_ENV=production
      - NEXT_PUBLIC_API_BASE_URL=https://api.tax-agent.local
      - NEXT_PUBLIC_APP_ENV=production
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.ui-review.rule=Host(`ui.tax-agent.local`)"
      - "traefik.http.routers.ui-review.entrypoints=websecure"
      - "traefik.http.routers.ui-review.tls=true"
      - "traefik.http.routers.ui-review.middlewares=auth@file"
    networks:
      - tax-agent-network
    restart: unless-stopped

networks:
  tax-agent-network:
    external: true

3. SSL/TLS Configuration

Ensure SSL certificates are properly configured in Traefik for HTTPS access.

Local Development

1. Install Dependencies

npm install

2. Set Environment Variables

cp .env.example .env.local
# Edit .env.local with your local API endpoints

3. Run Development Server

npm run dev

4. Run Tests

# Unit tests
npm run test

# E2E tests
npm run test:e2e

# Accessibility tests
npm run test:a11y

Monitoring and Logging

Health Checks

The application provides a health check endpoint at /api/health:

{
  "status": "healthy",
  "timestamp": "2024-01-10T15:30:00.000Z",
  "version": "1.0.0",
  "environment": "production"
}

Logging

Application logs are written to stdout and can be collected by Docker:

# View logs
docker-compose logs -f ui-review

# Export logs
docker-compose logs ui-review > app.log

Performance Monitoring

The application includes:

• Web Vitals reporting
• OpenTelemetry integration (when configured)
• Sentry error tracking (when configured)

Security Considerations

Authentication

• All routes require authentication via Traefik/Authentik
• No in-app authentication flows
• User claims are forwarded via headers

Content Security Policy

The application includes security headers:

• X-Frame-Options: DENY
• X-Content-Type-Options: nosniff
• Referrer-Policy: strict-origin-when-cross-origin

HTTPS

• Always use HTTPS in production
• Configure proper SSL certificates
• Enable HSTS headers in Traefik

Troubleshooting

Common Issues

1. Authentication not working

   • Check Traefik middleware configuration
   • Verify Authentik is running and accessible
   • Check forwarded headers in browser dev tools

2. API calls failing

   • Verify NEXT_PUBLIC_API_BASE_URL is correct
   • Check network connectivity to backend services
   • Review CORS configuration

3. Build failures

   • Ensure Node.js version is 20+
   • Clear npm cache: npm cache clean --force
   • Delete node_modules and reinstall

Debug Mode

Enable debug logging:

# Set environment variable
DEBUG=* npm run dev

# Or in Docker
docker-compose -f docker-compose.debug.yml up

Performance Issues

1. Check bundle size: npm run analyze
2. Review Lighthouse reports: npm run lighthouse
3. Monitor Web Vitals in production

Backup and Recovery

Configuration Backup

Backup these files:

• .env (production environment variables)
• docker-compose.yml
• Traefik configuration files

Data Recovery

The UI is stateless - all data is stored in backend services. No specific backup procedures required for the UI itself.

Updates and Maintenance

Updating the Application

1. Pull latest code
2. Build new Docker image
3. Update docker-compose.yml if needed
4. Deploy with zero downtime:

docker-compose pull
docker-compose up -d --no-deps ui-review

Security Updates

• Regularly update Node.js base image
• Update npm dependencies: npm audit fix
• Monitor security advisories

Support

For deployment issues:

1. Check application logs
2. Verify environment configuration
3. Test health endpoints
4. Review Traefik/Authentik logs if authentication issues