bytelyst-devops-tools/dashboard/DEPLOYMENT_GUIDE.md

# DevOps & Admin Dashboard Deployment Guide

## Overview

This guide covers deploying both the DevOps Dashboard and Platform Admin Dashboard using the existing Traefik gateway infrastructure, following the same pattern as the trading dashboard (https://invttrdg.bytelyst.com).

## URLs

- **DevOps Dashboard**: `https://devops.bytelyst.com`
- **Admin Dashboard**: `https://admin.bytelyst.com`
- **API Gateway**: `https://api.bytelyst.com`
  - Platform API: `https://api.bytelyst.com/platform/api`
  - DevOps API: `https://api.bytelyst.com/api/devops`

## Architecture

Both dashboards follow the same pattern as the trading dashboard:

```
Internet → Traefik Gateway → Services
                              ├─ DevOps Web (port 3049)
                              ├─ DevOps Backend (port 4004)
                              ├─ Admin Web (port 3001)
                              ├─ Platform Service (port 4003)
                              └─ Trading Dashboard (port 3085)
```

- **Traefik**: Acts as API gateway and reverse proxy
- **Docker Network**: All services connect via `learning_ai_common_plat_default`
- **Domain Routing**: Traefik routes based on host headers
- **SSL/TLS**: Managed by Traefik with Let's Encrypt

## Prerequisites

1. Platform stack running with Traefik gateway
2. Docker and Docker Compose installed
3. Domain names configured with DNS pointing to your server
4. Azure Cosmos DB account (shared with platform-service)
5. Platform Service running and accessible

## Quick Start

### 1. Start Platform Stack (if not running)

```bash
cd /opt/bytelyst/learning_ai_common_plat
docker-compose up -d
```

### 2. Deploy Dashboards

```bash
cd /opt/bytelyst/bytelyst-devops-tools/dashboard
./deploy.sh
```

This will:
- Deploy DevOps Dashboard (backend + web)
- Deploy Admin Dashboard via platform stack
- Run health checks
- Show deployment information

## Manual Deployment

### Deploy DevOps Dashboard

```bash
cd /opt/bytelyst/bytelyst-devops-tools/dashboard
docker-compose up -d --build
```

### Deploy Admin Dashboard

```bash
cd /opt/bytelyst/learning_ai_common_plat
docker-compose up -d admin-web
```

## Environment Configuration

### DevOps Dashboard (.env)

```bash
# Backend
PORT=4004
PLATFORM_SERVICE_URL=http://platform-service:4003
COSMOS_ENDPOINT=https://your-cosmos-account.documents.azure.com:443/
COSMOS_KEY=your-cosmos-primary-key
COSMOS_DATABASE=bytelyst-platform
JWT_SECRET=your-production-jwt-secret
CSRF_SECRET=your-production-csrf-secret
ENCRYPTION_KEY=your-production-encryption-key
PRODUCT_ID=bytelyst-devops
PRODUCT_NAME=ByteLyst DevOps Dashboard

# Azure Key Vault (optional)
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
AZURE_KEY_VAULT_URL=https://your-keyvault.vault.azure.net/

# Frontend
NEXT_PUBLIC_DEVOPS_API_URL=https://api.bytelyst.com/devops
NEXT_PUBLIC_PLATFORM_URL=https://api.bytelyst.com/platform/api
NEXT_PUBLIC_ADMIN_WEB_URL=https://admin.bytelyst.com
NEXT_PUBLIC_PRODUCT_ID=bytelyst-devops
NEXT_PUBLIC_PRODUCT_NAME=ByteLyst DevOps Dashboard
```

### Platform Dashboard (.env)

Add to your platform `.env`:

```bash
# Admin Web Dashboard
NEXT_PUBLIC_PLATFORM_URL=https://api.bytelyst.com/platform/api
NEXT_PUBLIC_DEVOPS_WEB_URL=https://devops.bytelyst.com
```

## Traefik Configuration

Both dashboards use Traefik labels for routing:

### DevOps Web
```yaml
labels:
  - 'traefik.enable=true'
  - 'traefik.http.routers.devops-web.rule=Host(`devops.bytelyst.com`)'
  - 'traefik.http.services.devops-web.loadbalancer.server.port=3000'
```

### DevOps Backend API
```yaml
labels:
  - 'traefik.enable=true'
  - 'traefik.http.routers.devops-api.rule=PathPrefix(`/api/devops`)'
  - 'traefik.http.services.devops-api.loadbalancer.server.port=4004'
```

### Admin Web
```yaml
labels:
  - 'traefik.enable=true'
  - 'traefik.http.routers.admin-web.rule=Host(`admin.bytelyst.com`)'
  - 'traefik.http.services.admin-web.loadbalancer.server.port=3001'
```

## DNS Configuration

Add DNS records pointing to your Traefik gateway server:

```
devops.bytelyst.com      A  <your-server-ip>
admin.bytelyst.com       A  <your-server-ip>
api.bytelyst.com         A  <your-server-ip>
```

## SSL/TLS Configuration

Traefik can automatically handle SSL certificates with Let's Encrypt. Add to your Traefik configuration:

```yaml
command:
  - '--certificatesresolvers.myresolver.acme.tlschallenge=true'
  - '--certificatesresolvers.myresolver.acme.email=admin@bytelyst.com'
  - '--certificatesresolvers.myresolver.acme.storage=/letsencrypt/acme.json'
```

Then update router labels:

```yaml
labels:
  - 'traefik.http.routers.devops-web.tls=true'
  - 'traefik.http.routers.devops-web.tls.certresolver=myresolver'
```

## Cross-Navigation Features

Both dashboards include cross-navigation links:

### DevOps Dashboard → Admin Dashboard
- Header includes "Platform Admin" link with Shield icon
- Opens admin dashboard in new tab
- Uses configured `NEXT_PUBLIC_ADMIN_WEB_URL`

### Admin Dashboard → DevOps Dashboard
- Sidebar includes "DevOps Dashboard" link with Server icon
- Opens devops dashboard in new tab
- Uses configured `NEXT_PUBLIC_DEVOPS_WEB_URL`

## Shared Authentication

Both dashboards use the same authentication system:

1. **Platform Service Auth**: Both authenticate against platform-service
2. **JWT Tokens**: Same JWT secret validates tokens across services
3. **Per-Product Access**: Admin access is checked per-product via membership roles
4. **Single Sign-On**: Users stay logged in across both dashboards

### Granting Access

To grant a user access to both dashboards:

1. Ensure user exists in platform-service
2. Add admin membership for both products:

```json
{
  "memberships": [
    {
      "productId": "bytelyst-devops",
      "role": "admin",
      "plan": "pro"
    },
    {
      "productId": "bytelyst-platform",
      "role": "admin",
      "plan": "pro"
    }
  ]
}
```

## Health Checks

- DevOps Backend: `http://localhost:4004/health`
- DevOps Web: `http://localhost:3049`
- Admin Web: `http://localhost:3001`
- Traefik Dashboard: `http://localhost:8080`

## Troubleshooting

### Network Issues
```bash
# Check if platform network exists
docker network inspect learning_ai_common_plat_default

# Check container connectivity
docker network inspect learning_ai_common_plat_default | grep devops
```

### Traefik Routing
```bash
# Check Traefik dashboard
http://localhost:8080

# Check Traefik logs
docker logs $(docker ps -q -f name=gateway)

# Check router configuration
docker inspect devops-web | grep -A 10 Labels
```

### Authentication Failures
- Verify JWT_SECRET matches across all services
- Check platform-service is accessible: `curl http://localhost:4003/health`
- Ensure user has proper product memberships

### Service Not Starting
```bash
# Check service logs
docker logs devops-backend
docker logs devops-web
docker logs admin-web

# Check health status
docker ps
docker inspect devops-backend | grep -A 5 Health
```

## Monitoring

Both dashboards include:
- Performance monitoring hooks
- Audit logging
- Health check endpoints
- Error tracking

Monitor these through:
- Traefik Dashboard: `http://localhost:8080`
- Grafana (if configured): `http://localhost:3000`
- Loki logs (if configured): `http://localhost:3100`

## Comparison with Trading Dashboard

| Feature | Trading | DevOps | Admin |
|---------|---------|--------|-------|
| Domain | invttrdg.bytelyst.com | devops.bytelyst.com | admin.bytelyst.com |
| Web Port | 3085 | 3049 | 3001 |
| Backend Port | 4018 | 4004 | N/A |
| Network | platform_net | platform_net | default |
| Traefik | Yes | Yes | Yes |
| Auth | Platform | Platform | Platform |

## Service Management

### Stop Services
```bash
cd /opt/bytelyst/bytelyst-devops-tools/dashboard
docker-compose down

cd /opt/bytelyst/learning_ai_common_plat
docker-compose stop admin-web
```

### Restart Services
```bash
cd /opt/bytelyst/bytelyst-devops-tools/dashboard
docker-compose restart

cd /opt/bytelyst/learning_ai_common_plat
docker-compose restart admin-web
```

### View Logs
```bash
# DevOps
docker logs -f devops-backend
docker logs -f devops-web

# Admin
docker logs -f admin-web

# Traefik
docker logs -f gateway
```

## Production Checklist

- [ ] Platform stack running with Traefik
- [ ] DNS records configured
- [ ] SSL/TLS certificates configured in Traefik
- [ ] Environment variables set for production
- [ ] Cosmos DB connection configured
- [ ] JWT_SECRET matches across all services
- [ ] User memberships configured for access
- [ ] Health checks passing
- [ ] Cross-navigation links working
- [ ] Monitoring and logging configured