bytelyst-devops-tools/DEPLOYMENT_GUIDE.md

# ByteLyst Production Deployment Guide

## Overview

This directory contains production deployment scripts for ByteLyst services.

## Production Repos

- `learning_ai_invt_trdg` - Trading Platform (https://api.bytelyst.com/invttrdg, https://invttrdg.bytelyst.com)
- `learning_ai_common_plat` - Platform Services (auth, flags, telemetry, etc.)
- `learning_ai_clock` - ChronoMind (AI-powered time management)
- `learning_ai_notes` - NoteLett (Agentic note-taking)

## Deployment Scripts

### 1. Single Repo Deployment (`deploy-invttrdg.sh`)

Deploy only the investment trading platform with comprehensive testing.

```bash
# Standard deployment (with dirty checks + smoke tests)
./deploy-invttrdg.sh

# Force deployment (skip dirty checks + smoke tests)
./deploy-invttrdg.sh --force

# Skip health checks and smoke tests
./deploy-invttrdg.sh --skip-health-check
```

**What it does:**
1. Dirty check (uncommitted changes, unpushed commits)
2. Pull and rebase origin/main
3. **Pre-deployment smoke tests:**
   - Backend contract checks (API, audit repository, WebSocket, session rules)
   - Web typecheck + production build
   - Web DOM smoke tests (auth, kill-switch, components)
   - Mobile typecheck compilation
4. Build and deploy Docker containers (backend + web)
5. **Post-deployment validation:**
   - Health checks on localhost endpoints
   - Production endpoint verification (api.bytelyst.com, invttrdg.bytelyst.com)
   - API smoke tests (health endpoint, content validation)
   - Web frontend validation (HTML content check)

### 2. Multi-Repo Deployment (`deploy-all.sh`)

Deploy all production repos or specific ones.

```bash
# Deploy all production repos
./deploy-all.sh

# Deploy specific repos
./deploy-all.sh learning_ai_invt_trdg learning_ai_clock

# Force deployment (skip dirty checks)
./deploy-all.sh --force

# Skip health checks
./deploy-all.sh --skip-health-check

# Deploy specific repos with force
./deploy-all.sh --force learning_ai_invt_trdg
```

**What it does:**
1. Runs dirty checks for each repo
2. Pulls and rebases origin/main for each repo
3. Builds and deploys Docker containers
4. Runs health checks on all services

## Service Endpoints

### Investment Trading (learning_ai_invt_trdg)
**Docker Services Deployed:**
- **Backend:** `invttrdg-backend` (port 4018 → mapped to 4025)
  - Trading engine + REST API + Socket.IO
  - Health endpoint: `/health/live`
  - API endpoints for trading operations
- **Web:** `invttrdg-web` (port 3085)
  - Vite SPA served via nginx
  - React trading interface

**Exposed Endpoints:**
- **Local Backend API:** http://localhost:4025
- **Local Web App:** http://localhost:3085
- **Production API:** https://api.bytelyst.com/invttrdg (via Caddy reverse proxy)
- **Production Web:** https://invttrdg.bytelyst.com (via Caddy reverse proxy)

### Platform Services (learning_ai_common_plat)
- **Platform Service:** http://localhost:4003
- **Extraction Service:** http://localhost:4005
- **MCP Server:** http://localhost:4007
- **Admin Web:** http://localhost:3001
- **Tracker Web:** http://localhost:3003

### ChronoMind (learning_ai_clock)
- **Backend:** http://localhost:4011
- **Web:** http://localhost:3030

### NoteLett (learning_ai_notes)
- **Backend:** http://localhost:4016
- **Web:** http://localhost:3000

## Docker Management

### Check running containers
```bash
docker ps
```

### View logs
```bash
# Specific repo
cd learning_ai_invttrdg
docker compose logs -f

# All containers
docker compose -f learning_ai_common_plat/docker-compose.ecosystem.yml logs -f
```

### Restart services
```bash
# Specific repo
cd learning_ai_invttrdg
docker compose restart

# All services
docker compose -f learning_ai_common_plat/docker-compose.ecosystem.yml restart
```

### Stop services
```bash
# Specific repo
cd learning_ai_invttrdg
docker compose down

# All services
docker compose -f learning_ai_common_plat/docker-compose.ecosystem.yml down
```

## Troubleshooting

### Dirty Check Failures

If deployment fails due to uncommitted changes:
```bash
# Option 1: Commit changes
cd learning_ai_invttrdg
git add .
git commit -m "Your commit message"

# Option 2: Stash changes
git stash

# Option 3: Force deployment
./deploy-invttrdg.sh --force
```

### Rebase Conflicts

If rebase fails due to conflicts:
```bash
cd learning_ai_invttrdg
# Resolve conflicts
git add .
git rebase --continue
```

### Health Check Failures

If health checks fail but services are starting:
```bash
# Skip health checks and smoke tests
./deploy-invttrdg.sh --skip-health-check

# Check manually
curl http://localhost:4025/health/live
curl http://localhost:3085
```

### Smoke Test Failures

If pre-deployment smoke tests fail:
```bash
# Run smoke tests manually to debug
cd learning_ai_invt_trdg
./scripts/smoke-release.sh

# Run individual backend checks
cd backend
npm run check:api-contract
npm run check:websocket-contract
npm run check:session-rule-normalization

# Run web tests individually
cd ../web
pnpm vitest run src/components/Login.dom.test.tsx
```

### Docker Build Failures

If Docker build fails:
```bash
# Clean build
cd learning_ai_invttrdg
docker compose build --no-cache

# Check disk space
df -h
```

## DNS Configuration

DNS is managed via GoDaddy. To update DNS records:

```bash
cd learning_ai_common_plat
./scripts/godaddy-sync-bytelyst-dns.sh --ip <YOUR_VM_IP> --validate
```

## Monitoring

### Health Check Script
```bash
./check-health.sh
```

### View Logs
- **Grafana:** http://localhost:3000 (admin/bytelyst)
- **Loki:** http://localhost:3100
- **Traefik Dashboard:** http://localhost:8080

## Production Checklist

Before deploying to production:

- [ ] All tests pass locally
- [ ] No uncommitted changes
- [ ] No unpushed commits
- [ ] Environment variables are set correctly
- [ ] DNS records point to correct IP
- [ ] Database migrations are applied
- [ ] Backup current deployment
- [ ] Monitor logs after deployment

## Rollback

If deployment causes issues:

```bash
cd learning_ai_invttrdg
# Revert to previous commit
git log --oneline -5
git revert <commit-hash>

# Redeploy
docker compose up -d --build
```