siriusscan--sirius/documentation/dev-notes/archive/TERMINAL-SSR-HANDOFF.md

Terminal SSR Fix Handoff Document

Date: December 7, 2024
Issue: Terminal component infinite loop after SSR fix
Status: REQUIRES DEVELOPER ATTENTION

🚨 Problem Summary

While successfully fixing the Server-Side Rendering (SSR) issue that prevented the UI from building, the terminal component now exhibits severe runtime problems:

1. Infinite Loop: The terminal component triggers continuous re-initialization
2. API Timeout: Agent listing API calls are timing out after 30 seconds
3. Session Management Issues: Multiple overlapping session initialization attempts

📋 What Was Changed

Original Structure (Working)

• Single File: pages/terminal.tsx contained all terminal logic
• Direct Imports: xterm libraries imported at top-level
• SSR Problem: Build failed due to self is not defined error

New Structure (SSR Fixed, Runtime Broken)

pages/terminal.tsx           → Simple page wrapper
components/TerminalWrapper.tsx → Dynamic import wrapper
components/DynamicTerminal.tsx → All terminal logic (moved from page)

Key Changes Made

1. Extracted terminal logic from pages/terminal.tsx to components/DynamicTerminal.tsx
2. Added dynamic import with ssr: false in TerminalWrapper.tsx
3. Moved all xterm imports to client-side only component

🔍 Identified Issues

1. UseEffect Dependency Array Problem

// Line 488 in DynamicTerminal.tsx
}, [executeCommand, initializeSession, writePrompt, agentsQuery.data]);

Issue: Including agentsQuery.data in dependencies causes infinite re-initialization when:

• Component mounts → API call starts → Data updates → useEffect triggers → New API call → Loop

2. API Query Configuration Issue

// Line 145 in DynamicTerminal.tsx
const agentsQuery = api.terminal.listAgents.useQuery(undefined, {
  refetchInterval: 10000, // Keep polling agent list
});

Issue: Aggressive polling combined with useEffect dependency creates a feedback loop

3. Session Management Overlap

// Lines 320-330 in DynamicTerminal.tsx
try {
  await initializeSession.mutateAsync({
    target: currentTargetRef.current,
  });
  console.log("[Terminal init] Initial session successful.");
} catch (error) {
  console.error("[Terminal init] Initial session failed:", error);
}

Issue: Multiple session initialization attempts due to component re-mounting

🛠️ Recommended Fixes

Priority 1: Fix useEffect Dependencies

// REMOVE agentsQuery.data from dependency array
}, [executeCommand, initializeSession, writePrompt]);

Priority 2: Separate Agent List Query

// Move agent query to separate useEffect with its own dependencies
useEffect(() => {
  // Handle agent list updates separately
}, []);

Priority 3: Add Cleanup Logic

// Ensure proper cleanup on unmount
useEffect(() => {
  // ... terminal setup
  return () => {
    // Cancel any pending API calls
    terminal.current?.dispose();
    terminal.current = null;
    resizeObserver.disconnect();
  };
}, []);

🔧 Backend API Investigation

Agent List Timeout

Location: sirius-ui/src/server/api/routers/terminal.ts:208

const response = await waitForResponse(AGENT_RESPONSE_QUEUE);

Issue: The listAgents API is waiting 30 seconds for a response that may not come due to:

1. RabbitMQ connection issues
2. Agent service not running
3. Queue misconfiguration

Recommended Backend Check

# Check if agent service is responding to list_agents action
docker exec sirius-engine ps aux | grep agent
docker logs sirius-engine | grep -i agent

Current Backend Status (as of handoff)

# Agent binary exists but service has path warning
$ docker exec sirius-engine ls -la /app-agent
total 10896
-rwxr-xr-x 1 sirius sirius 11141272 Jun  7 17:45 agent

# Engine logs show warning about agent service
Warning: Agent service path not found or invalid

⚠️ Backend Issue Detected: The sirius-engine shows "Agent service path not found or invalid" warning, which explains why the listAgents API is timing out. The agent binary exists but the service may not be properly configured or running.

🎯 Developer Action Items

Immediate (Critical)

1. Fix useEffect dependencies in DynamicTerminal.tsx
2. Remove agentsQuery.data from the main useEffect dependency array
3. Test terminal initialization without infinite loops

Secondary (Important)

1. Investigate agent API timeout - check backend service status
2. Add proper error boundaries around terminal component
3. Implement session cleanup on component unmount

Testing (Verification)

1. Monitor console logs for initialization messages
2. Verify single session creation per page load
3. Test agent list loading without timeouts

📊 Log Patterns to Watch

Good (Expected)

[Terminal useEffect] Initializing xterm...
[Terminal useEffect] Xterm opened.
[Terminal init] Initial session successful.

Bad (Current State)

[Terminal useEffect] Initializing xterm...  (repeating)
[Terminal] Failed to list agents: Error: Command timed out

🔄 Rollback Option

If issues persist, the SSR problem can be solved alternatively by:

1. Conditional rendering based on typeof window !== 'undefined'
2. Next.js NoSSR component wrapper
3. Lazy loading with React.lazy() instead of dynamic imports

These approaches would allow reverting to the original single-file structure while maintaining SSR compatibility.

📞 Contact Information

Original Implementation: Located in git history before SSR fix commit Testing Environment: Docker compose with sirius-ui service Key Files:

• components/DynamicTerminal.tsx (main issue)
• server/api/routers/terminal.ts (backend timeout)
• components/TerminalWrapper.tsx (wrapper)

---

✅ What Is Working

SSR Fix (Successful)

• Build Process: No more self is not defined errors
• Container Builds: UI builds successfully in Docker
• Page Loading: Terminal page loads without SSR crashes
• Dynamic Imports: Client-side xterm loading works correctly

Backend Services (Operational)

• Database: Postgres running and accessible
• API: sirius-api health endpoint responding (http://localhost:9001/health)
• Queue: RabbitMQ running and connected
• Cache: Valkey operational

UI Components (Functional)

• Main App: Home page and routing working
• Authentication: NextAuth integration intact
• API Routes: TRPC endpoints accessible
• Static Assets: All styles and assets loading

Note: The SSR fix itself is correct and should be maintained. The issues are in the React lifecycle management and API integration patterns that were disrupted during the refactoring process.

🔧 Development Environment Setup

Current Status (Ready for Development)

# All services running in development mode
$ docker compose ps
NAME              STATUS         PORTS
sirius-api        Up 7 minutes   0.0.0.0:9001->9001/tcp
sirius-engine     Up 7 minutes   0.0.0.0:5174->5174/tcp, 0.0.0.0:50051->50051/tcp
sirius-postgres   Up 7 minutes   0.0.0.0:5432->5432/tcp
sirius-rabbitmq   Up 7 minutes   0.0.0.0:5672->5672/tcp, 0.0.0.0:15672->15672/tcp
sirius-ui         Up 4 minutes   0.0.0.0:3000->3000/tcp (Next.js dev server)
sirius-valkey     Up 7 minutes   0.0.0.0:6379->6379/tcp

Development Mode Features

• Live Code Reload: Changes to sirius-ui/ files trigger automatic rebuilds
• Source Maps: Full debugging support in browser dev tools
• Hot Module Replacement: React components update without page refresh
• Volume Mounts: Local code mounted at /app in containers

Quick Development Commands

# Restart UI with code changes
docker compose restart sirius-ui

# View live logs
docker compose logs -f sirius-ui

# Access container shell for debugging
docker exec -it sirius-ui sh

# Stop all services
docker compose down

URLs for Testing

• UI: http://localhost:3000 (Next.js dev server)
• Terminal Page: http://localhost:3000/terminal (SSR fixed, but has infinite loop)
• API Health: http://localhost:9001/health
• RabbitMQ Management: http://localhost:15672 (guest/guest)

---

✅ DOCKER DEVELOPMENT SETUP COMPLETED

Multi-Stage Docker Implementation

Status: ✅ COMPLETED - Proper Docker best practices implemented

Solution Summary

The Docker development issues have been completely resolved using a multi-stage Dockerfile approach:

1. Architecture Issues: ✅ Fixed - Dependencies now compile in correct container architecture
2. npm Install Failures: ✅ Fixed - Proper staging prevents conflicts
3. Prisma Generation: ✅ Fixed - Generated during build stage, not runtime
4. Development Hot Reloading: ✅ Working - Source code changes trigger rebuilds
5. Volume Mounting Strategy: ✅ Optimized - Source mounted, node_modules isolated

Implementation Details

Multi-Stage Dockerfile (sirius-ui/Dockerfile):

• Base Stage: Common dependencies and npm script fixes
• Development Stage: Dev dependencies, Prisma generation, dev server
• Production Stage: Optimized runtime build

Development Configuration (docker-compose.override.yml):

• Target: development stage for full dev features
• Volume Mounts: Source code only, node_modules preserved in container
• Environment: Development-specific variables and database connection

Production Configuration (docker-compose.prod.yml):

• Target: production stage for optimized runtime
• No Volumes: Uses built image as-is for production

Verification Results

# ✅ Container starts successfully
$ docker compose up sirius-ui -d
[+] Running 3/3
 ✔ Volume "sirius_node_modules"  Created
 ✔ Container sirius-postgres     Running
 ✔ Container sirius-ui           Started

# ✅ Next.js dev server running
$ docker exec sirius-ui ps aux
nextjs    1  npm run dev
nextjs   28  node /app/node_modules/.bin/next dev
nextjs   39  next-router-worker

# ✅ UI accessible and working
$ curl -s http://localhost:3000 | head -2
<!DOCTYPE html><html lang="en">...

# ✅ Prisma installed and working
$ docker exec sirius-ui npx prisma --version
prisma                  : 5.1.1
@prisma/client          : 5.1.1
Current platform        : linux-musl-arm64-openssl-3.0.x

# ✅ Volume mounting working
$ touch sirius-ui/src/test.txt
$ docker exec sirius-ui ls /app/src/test.txt
/app/src/test.txt

Usage Commands

Development Mode (Default):

# Start development environment
docker compose up sirius-ui -d

# View development logs
docker compose logs sirius-ui -f

# Access development container
docker exec -it sirius-ui sh

Production Mode:

# Build and run production image
docker compose -f docker-compose.yml -f docker-compose.prod.yml up sirius-ui -d

Rebuild After Changes:

# Rebuild development image
docker compose build sirius-ui
docker compose up sirius-ui -d

Architecture Benefits Achieved

1. Proper Separation: Development and production stages serve different needs
2. Architecture Compatibility: Dependencies compile in target architecture
3. Fast Development: Source changes trigger immediate rebuilds
4. Production Optimization: Minimal production image with only runtime dependencies
5. Developer Experience: Standard Docker commands work as expected

🎯 READY FOR HANDOFF: The Docker development environment is now properly configured following industry best practices. The next developer can focus entirely on fixing the terminal component infinite loop issue without Docker concerns.

---

✅ DATABASE SETUP COMPLETED

Prisma Database Issue Resolution

Status: ✅ COMPLETED - Database tables created and seeded successfully

Problem Summary

After implementing the Docker development setup, login attempts failed with database errors:

The table `public.users` does not exist in the current database.

Root Cause: Prisma client generation creates TypeScript client code but doesn't create actual database tables. Database migrations were never run.

Solution Implemented

1. Created Initial Migration:

   docker exec sirius-ui npx prisma migrate dev --name init
   

   • Created migrations/20250607191550_init/migration.sql
   • Applied migration to create all tables: users, hosts, ports, scans, vulnerabilities

2. Fixed Seed Script Configuration:

   • Updated package.json seed command from bun to npx tsx
   • Installed tsx dependency for TypeScript execution
   • Successfully seeded admin user (username: admin, password: password)

3. Automated Database Setup:

   • Created start-dev.sh script that handles database setup on container start
   • Updated Dockerfile to run migrations and seeding automatically
   • Development containers now self-initialize database state

Verification Results

# ✅ Database tables created
$ docker exec sirius-postgres psql -U postgres -d postgres -c "\dt"
 public | users              | table | postgres
 public | hosts              | table | postgres
 public | ports              | table | postgres
 public | scans              | table | postgres
 public | vulnerabilities    | table | postgres

# ✅ Admin user seeded
$ docker exec sirius-postgres psql -U postgres -d postgres -c "SELECT name, email FROM users;"
 admin | admin@example.com

# ✅ Startup script working
🚀 Starting Sirius UI Development Server...
📁 Applying database migrations...
No pending migrations to apply.
🌱 Running database seed...
Admin user updated with new password: admin
🎯 Starting Next.js development server...

# ✅ Login page accessible
$ curl -s http://localhost:3000 | grep "Join the Pack"
Join the Pack

Login Credentials

• Username: admin
• Password: password
• Email: admin@example.com

Database Schema

The following tables are now available:

• users: Authentication and user management
• hosts: Scanned host information
• ports: Port scan results
• vulnerabilities: Vulnerability scan results
• scans: Scan job tracking

Automated Setup Features

Development Mode: Database automatically initializes on container start

• Applies any pending migrations
• Seeds initial admin user
• Handles existing data gracefully (updates vs creates)

Production Mode: Same migration system applies for production deployments

🎯 LOGIN FUNCTIONALITY RESTORED: Users can now successfully log in to the application using the admin credentials. The database infrastructure is fully operational and ready for development.