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

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

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

### 2. Run with Docker Compose

```bash
docker-compose up -d
```

### 3. Verify Deployment

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

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

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

```bash
npm install
```

### 2. Set Environment Variables

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

### 3. Run Development Server

```bash
npm run dev
```

### 4. Run Tests

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

```json
{
  "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:

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

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

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