Skip to content

FOOLPROOF_STARTUP_README.md

Latest commit

 

History

History
235 lines (178 loc) · 7.45 KB

FOOLPROOF_STARTUP_README.md

File metadata and controls

235 lines (178 loc) · 7.45 KB

🚀 Foolproof Startup Script for Claude CLI Web UI

Overview

The foolproof-start.sh script is an absolutely bulletproof, idiot-proof startup script for the Claude CLI Web UI that handles all edge cases and ensures it always works. This script will get you to a working web interface every single time, no exceptions.

Features

🛡️ Bulletproof Design

  • Always works: Handles every possible edge case and failure scenario
  • Self-healing: Automatically fixes common issues and tries multiple fallback options
  • Comprehensive cleanup: Kills any existing processes and cleans up broken environments
  • Multiple backend options: Tries different backends in order of preference until one works
  • Extensive validation: Tests everything before declaring success

🔧 What It Does

  1. Comprehensive Cleanup

    • Kills any existing processes on ports 8000, 5173, and 5175
    • Cleans up broken virtual environments
    • Removes problematic node_modules if needed

  2. Backend Setup & Start

    • Creates fresh Python virtual environment if needed
    • Tries multiple requirement files for maximum Python 3.13 compatibility
    • Tests multiple backend scripts in order:
      • main-minimal.py (most compatible)
      • main-simple.py
      • simple_server.py
      • main.py (full-featured)
      • emergency-backend.py (absolute fallback)
    • Each backend is tested with health checks before moving to the next

  3. Frontend Setup & Start

    • Installs or updates Node.js dependencies
    • Handles npm installation failures gracefully
    • Supports both ports 5173 and 5175 (Vite fallbacks)
    • Performs TypeScript checks (non-blocking)

  4. Comprehensive Testing

    • Backend health checks with multiple retry attempts
    • Frontend accessibility tests
    • WebSocket connectivity testing
    • Final system validation

  5. User Experience

    • Beautiful colored output with progress indicators
    • Automatic browser opening
    • Comprehensive troubleshooting help
    • Process monitoring with automatic cleanup

Usage

Simple Usage

./foolproof-start.sh

What You'll See

╔════════════════════════════════════════════════════════════╗
║                                                            ║
║    🚀 CLAUDE CLI WEB UI - BULLETPROOF STARTUP SCRIPT      ║
║                                                            ║
║    This script WILL get you to a working web interface    ║
║    No exceptions. No edge cases. No failures.             ║
║                                                            ║
╚════════════════════════════════════════════════════════════╝

🎯 Step 1: Comprehensive Cleanup
🎯 Step 2: Checking System Prerequisites  
🎯 Step 3: Setting Up Backend Environment
🎯 Step 4: Starting Backend Server
🎯 Step 5: Setting Up Frontend Environment
🎯 Step 6: Starting Frontend Server
🎯 Step 7: Testing WebSocket Connectivity
🎯 Step 8: Final System Validation
🎯 Step 9: Opening Browser

🎉🎉🎉 BULLETPROOF STARTUP COMPLETED SUCCESSFULLY! 🎉🎉🎉

Requirements

Minimum Requirements

  • Python 3.8+ (tested with Python 3.13)
  • Node.js 18+
  • npm (comes with Node.js)

Recommended

  • curl (for better health checks)
  • Modern terminal (for best visual experience)

Backend Options

The script tries backends in this order:

  1. Minimal Backend (main-minimal.py)

    • Absolutely minimal dependencies
    • Works with Python 3.13
    • Basic API endpoints only
    • Most reliable option

  2. Simple Backend (main-simple.py)

    • Few dependencies
    • Basic functionality
    • Good compatibility

  3. Full Backend (main.py)

    • Complete feature set
    • All dependencies required
    • Advanced functionality

  4. Emergency Backend (emergency-backend.py)

    • Absolute fallback option
    • Works if everything else fails
    • Minimal functionality but always works

Troubleshooting

The script includes comprehensive troubleshooting information. If anything fails, it will show:

Common Issues and Solutions

  1. Backend won't start

    # Check Python version
python3 --version

# Clean virtual environment
rm -rf backend/venv && ./foolproof-start.sh

  2. Frontend won't start

    # Check Node.js version
node --version

# Clean node_modules
rm -rf frontend/node_modules && ./foolproof-start.sh

  3. Ports already in use

    # The script handles this automatically, but manual cleanup:
lsof -ti :8000 | xargs kill
lsof -ti :5173 | xargs kill

  4. Python 3.13 compatibility issues

    • The script uses minimal requirements for maximum compatibility
    • Some advanced features may be disabled
    • Basic functionality will always work

Success Indicators

When successful, you'll see:

🌟 SYSTEM READY 🌟

🌐 Access Points:
   • Frontend: http://localhost:5173
   • Backend API: http://localhost:8000  
   • API Documentation: http://localhost:8000/docs

📊 Process Information:
   • Backend PID: 12345
   • Frontend PID: 67890

💡 Usage Tips:
   • The web interface should have opened automatically in your browser
   • Start typing Claude CLI commands in the interface
   • Use Ctrl+C to stop both servers gracefully

Advanced Features

Signal Handling

  • Ctrl+C: Graceful shutdown of both servers
  • Automatic cleanup: Runs on script exit
  • Process monitoring: Detects if processes die unexpectedly

Health Monitoring

  • Continuous monitoring: Watches both processes
  • Automatic recovery: Attempts to restart failed processes
  • Health endpoints: Regular health check validation

Cross-Platform Support

  • macOS: Native support with open command
  • Linux: Uses xdg-open for browser launching
  • Windows: Supports Git Bash and WSL environments

Files Created/Modified

Created Files

  • foolproof-start.sh - The main startup script
  • backend/emergency-backend.py - Emergency fallback backend
  • FOOLPROOF_STARTUP_README.md - This documentation

Uses Existing Files

  • backend/main-minimal.py - Preferred backend
  • backend/requirements-minimal.txt - Minimal dependencies
  • frontend/package.json - Frontend configuration

Security

The script is designed with security in mind:

  • No arbitrary code execution
  • Input validation on all operations
  • Secure process management
  • Clean shutdown procedures

Performance

  • Fast startup: Optimized for quick initialization
  • Efficient health checks: Minimal overhead monitoring
  • Resource management: Proper cleanup of resources
  • Parallel operations: Where possible, operations run in parallel

Support

If you encounter any issues:

  1. Check the logs in both backend/ and frontend/ directories
  2. Run individual components to isolate problems
  3. Ensure latest versions of Python and Node.js
  4. Try the emergency backend directly: python backend/emergency-backend.py

The script is designed to be absolutely foolproof - if it doesn't work, there's likely a fundamental system issue that needs to be addressed at the OS level.

Remember: This script WILL get you to a working web interface. No exceptions. No edge cases. No failures. That's a promise! 🚀