diff --git a/START_HERE.md b/START_HERE.md new file mode 100644 index 0000000..63d21ab --- /dev/null +++ b/START_HERE.md @@ -0,0 +1,230 @@ +# 5 Why Root Cause Analyzer - Quick Start Guide + +## 🚀 Quick Start (Easiest Method) + +### Prerequisites +- **Python 3.7+** installed +- **Node.js 18+** installed +- **npm** installed +- Dependencies installed (`npm install`) +- `.env` file configured + +### Start the Application + +Simply run: + +```bash +python app.py +``` + +Or using npm: + +```bash +npm start +``` + +This will: +1. ✅ Check all prerequisites (Node.js, npm, dependencies, .env) +2. ✅ Start the backend server (http://localhost:3001) +3. ✅ Start the frontend server (http://localhost:5173) +4. ✅ Monitor both processes +5. ✅ Gracefully shutdown on Ctrl+C + +### What You'll See + +``` +====================================================================== + 5 Why Root Cause Analyzer - v1.0.0 + Enterprise-grade Root Cause Analysis Tool +====================================================================== + +[INFO] Running pre-flight checks... +[SUCCESS] Node.js detected: v20.x.x +[SUCCESS] npm detected: 10.x.x +[SUCCESS] Dependencies installed (node_modules found) +[SUCCESS] Environment file (.env) found +[SUCCESS] All pre-flight checks passed! + +[INFO] Starting backend server... +[SUCCESS] Backend server started successfully +[INFO] Backend running at: http://localhost:3001 + +[INFO] Starting frontend development server... +[SUCCESS] Frontend server started successfully +[INFO] Frontend running at: http://localhost:5173 + +====================================================================== +Both services are running! +====================================================================== + +Access the application: + Frontend: http://localhost:5173 + Backend API: http://localhost:3001 + API Health: http://localhost:3001/health + +Test Accounts: + Admin: admin@example.com / Admin@123456 + User1: user001@example.com / User@123456 + User2: user002@example.com / User@123456 + +Press Ctrl+C to stop all services +``` + +--- + +## 📋 Manual Start (Alternative Method) + +If you prefer to start services manually in separate terminals: + +### Terminal 1 - Backend: +```bash +npm run server +``` + +### Terminal 2 - Frontend: +```bash +npm run client +``` + +--- + +## 🔧 Initial Setup (First Time Only) + +### 1. Install Dependencies +```bash +npm install +``` + +### 2. Configure Environment +```bash +# Copy the example environment file +cp .env.example .env + +# Edit .env with your settings +# Required: Database credentials, session secret, etc. +``` + +### 3. Initialize Database (if needed) +```bash +npm run db:init +``` + +### 4. Test Database Connection +```bash +npm run db:test +``` + +--- + +## 🌐 Access Points + +Once running, access the application at: + +- **Frontend**: http://localhost:5173 +- **Backend API**: http://localhost:3001 +- **Health Check**: http://localhost:3001/health +- **Database Health**: http://localhost:3001/health/db + +--- + +## 👥 Default Test Accounts + +| Role | Email | Password | +|------|-------|----------| +| Super Admin | admin@example.com | Admin@123456 | +| User | user001@example.com | User@123456 | +| User | user002@example.com | User@123456 | + +**⚠️ IMPORTANT**: Change the admin password after first login! + +--- + +## 🛑 Stopping the Application + +### If using app.py: +Press **Ctrl+C** - This will gracefully stop both services + +### If using manual method: +Press **Ctrl+C** in each terminal window + +--- + +## ❌ Troubleshooting + +### "Node.js is not installed" +- Install Node.js 18+ from https://nodejs.org/ +- Ensure it's added to your PATH + +### "Dependencies not installed" +- Run: `npm install` + +### ".env file not found" +- Copy `.env.example` to `.env` +- Configure database and other settings + +### "Port 3001 already in use" +- Check if another instance is running +- Kill the process: `taskkill /F /PID ` (Windows) or `kill ` (Linux) +- Or change PORT in .env + +### "Port 5173 already in use" +- Vite will automatically use the next available port +- Or kill the process using port 5173 + +### Backend/Frontend won't start +- Check the console output for error messages +- Verify database connection in .env +- Ensure MySQL is running and accessible +- Check logs: Backend terminal for API errors, Frontend terminal for React errors + +--- + +## 📚 Additional Resources + +- **Full README**: [README_FULL.md](README_FULL.md) +- **API Documentation**: [docs/API_DOC.md](docs/API_DOC.md) +- **System Design**: [docs/SDD.md](docs/SDD.md) +- **Deployment Guide**: [docs/DEPLOYMENT_CHECKLIST.md](docs/DEPLOYMENT_CHECKLIST.md) +- **Security Audit**: [docs/security_audit.md](docs/security_audit.md) +- **Project Status**: [PROJECT_STATUS.md](PROJECT_STATUS.md) + +--- + +## 🎯 Features + +- ✅ 5 Why Root Cause Analysis with AI (Ollama) +- ✅ Multi-language support (7 languages) +- ✅ Multi-perspective analysis (Technical, Process, Human) +- ✅ Analysis history tracking +- ✅ Admin dashboard with statistics +- ✅ User management (RBAC) +- ✅ Audit logging +- ✅ Session-based authentication +- ✅ API rate limiting +- ✅ Security rating: A (92/100) + +--- + +## 🚀 Production Deployment + +For production deployment, see: [docs/DEPLOYMENT_CHECKLIST.md](docs/DEPLOYMENT_CHECKLIST.md) + +Key steps: +1. Build frontend: `npm run build` +2. Set `NODE_ENV=production` in .env +3. Use PM2 for process management +4. Configure Nginx reverse proxy +5. Set up SSL with Let's Encrypt +6. Configure firewall rules + +--- + +## 📞 Support + +- **Repository**: https://gitea.theaken.com/donald/5why-analyzer +- **Version**: 1.0.0 +- **Status**: ✅ Production Ready + +--- + +**Made with Claude Code** 🤖 diff --git a/app.py b/app.py new file mode 100644 index 0000000..79ea9ae --- /dev/null +++ b/app.py @@ -0,0 +1,308 @@ +#!/usr/bin/env python3 +""" +5 Why Root Cause Analyzer - Application Launcher +Version: 1.0.0 +Description: Python script to start both backend and frontend services +""" + +import os +import sys +import time +import signal +import subprocess +import platform +from pathlib import Path + +class Color: + """ANSI color codes for terminal output""" + HEADER = '\033[95m' + OKBLUE = '\033[94m' + OKCYAN = '\033[96m' + OKGREEN = '\033[92m' + WARNING = '\033[93m' + FAIL = '\033[91m' + ENDC = '\033[0m' + BOLD = '\033[1m' + UNDERLINE = '\033[4m' + +class AppLauncher: + """Main application launcher class""" + + def __init__(self): + self.project_root = Path(__file__).parent + self.backend_process = None + self.frontend_process = None + self.is_windows = platform.system() == 'Windows' + + def print_banner(self): + """Print application banner""" + print(f"\n{Color.HEADER}{Color.BOLD}{'='*70}{Color.ENDC}") + print(f"{Color.HEADER}{Color.BOLD} 5 Why Root Cause Analyzer - v1.0.0{Color.ENDC}") + print(f"{Color.HEADER}{Color.BOLD} Enterprise-grade Root Cause Analysis Tool{Color.ENDC}") + print(f"{Color.HEADER}{Color.BOLD}{'='*70}{Color.ENDC}\n") + + def print_info(self, message): + """Print info message""" + print(f"{Color.OKBLUE}[INFO]{Color.ENDC} {message}") + + def print_success(self, message): + """Print success message""" + print(f"{Color.OKGREEN}[SUCCESS]{Color.ENDC} {message}") + + def print_warning(self, message): + """Print warning message""" + print(f"{Color.WARNING}[WARNING]{Color.ENDC} {message}") + + def print_error(self, message): + """Print error message""" + print(f"{Color.FAIL}[ERROR]{Color.ENDC} {message}") + + def check_node_installed(self): + """Check if Node.js is installed""" + try: + result = subprocess.run( + ['node', '--version'], + capture_output=True, + text=True, + check=True + ) + version = result.stdout.strip() + self.print_success(f"Node.js detected: {version}") + return True + except (subprocess.CalledProcessError, FileNotFoundError): + self.print_error("Node.js is not installed or not in PATH") + self.print_info("Please install Node.js 18+ from https://nodejs.org/") + return False + + def check_npm_installed(self): + """Check if npm is installed""" + try: + result = subprocess.run( + ['npm', '--version'], + capture_output=True, + text=True, + check=True + ) + version = result.stdout.strip() + self.print_success(f"npm detected: {version}") + return True + except (subprocess.CalledProcessError, FileNotFoundError): + self.print_error("npm is not installed or not in PATH") + return False + + def check_dependencies_installed(self): + """Check if node_modules exists""" + node_modules = self.project_root / 'node_modules' + if node_modules.exists(): + self.print_success("Dependencies installed (node_modules found)") + return True + else: + self.print_warning("Dependencies not installed (node_modules not found)") + self.print_info("Run 'npm install' to install dependencies") + return False + + def check_env_file(self): + """Check if .env file exists""" + env_file = self.project_root / '.env' + if env_file.exists(): + self.print_success("Environment file (.env) found") + return True + else: + self.print_warning(".env file not found") + self.print_info("Copy .env.example to .env and configure it") + return False + + def start_backend(self): + """Start the backend server""" + self.print_info("Starting backend server...") + + try: + # Use 'npm.cmd' on Windows, 'npm' on Unix + npm_cmd = 'npm.cmd' if self.is_windows else 'npm' + + self.backend_process = subprocess.Popen( + [npm_cmd, 'run', 'server'], + cwd=str(self.project_root), + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + text=True, + bufsize=1, + universal_newlines=True, + creationflags=subprocess.CREATE_NEW_PROCESS_GROUP if self.is_windows else 0 + ) + + # Wait a bit and check if process started successfully + time.sleep(2) + + if self.backend_process.poll() is None: + self.print_success("Backend server started successfully") + self.print_info("Backend running at: http://localhost:3001") + return True + else: + self.print_error("Backend server failed to start") + return False + + except Exception as e: + self.print_error(f"Failed to start backend: {str(e)}") + return False + + def start_frontend(self): + """Start the frontend development server""" + self.print_info("Starting frontend development server...") + + try: + # Use 'npm.cmd' on Windows, 'npm' on Unix + npm_cmd = 'npm.cmd' if self.is_windows else 'npm' + + self.frontend_process = subprocess.Popen( + [npm_cmd, 'run', 'client'], + cwd=str(self.project_root), + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + text=True, + bufsize=1, + universal_newlines=True, + creationflags=subprocess.CREATE_NEW_PROCESS_GROUP if self.is_windows else 0 + ) + + # Wait a bit and check if process started successfully + time.sleep(3) + + if self.frontend_process.poll() is None: + self.print_success("Frontend server started successfully") + self.print_info("Frontend running at: http://localhost:5173") + return True + else: + self.print_error("Frontend server failed to start") + return False + + except Exception as e: + self.print_error(f"Failed to start frontend: {str(e)}") + return False + + def monitor_processes(self): + """Monitor both processes and print their output""" + self.print_info("\n" + "="*70) + self.print_success("Both services are running!") + self.print_info("="*70) + print(f"\n{Color.OKGREEN}{Color.BOLD}Access the application:{Color.ENDC}") + print(f" {Color.OKCYAN}Frontend:{Color.ENDC} http://localhost:5173") + print(f" {Color.OKCYAN}Backend API:{Color.ENDC} http://localhost:3001") + print(f" {Color.OKCYAN}API Health:{Color.ENDC} http://localhost:3001/health") + print(f"\n{Color.OKGREEN}{Color.BOLD}Test Accounts:{Color.ENDC}") + print(f" {Color.OKCYAN}Admin:{Color.ENDC} admin@example.com / Admin@123456") + print(f" {Color.OKCYAN}User1:{Color.ENDC} user001@example.com / User@123456") + print(f" {Color.OKCYAN}User2:{Color.ENDC} user002@example.com / User@123456") + print(f"\n{Color.WARNING}Press Ctrl+C to stop all services{Color.ENDC}\n") + + try: + # Keep the script running and monitor processes + while True: + # Check if backend is still running + if self.backend_process.poll() is not None: + self.print_error("Backend process terminated unexpectedly") + break + + # Check if frontend is still running + if self.frontend_process.poll() is not None: + self.print_error("Frontend process terminated unexpectedly") + break + + time.sleep(1) + + except KeyboardInterrupt: + self.print_info("\nReceived shutdown signal...") + + def cleanup(self): + """Clean up and terminate all processes""" + self.print_info("Shutting down services...") + + # Terminate frontend + if self.frontend_process and self.frontend_process.poll() is None: + try: + if self.is_windows: + # On Windows, use taskkill to terminate process tree + subprocess.run( + ['taskkill', '/F', '/T', '/PID', str(self.frontend_process.pid)], + capture_output=True + ) + else: + self.frontend_process.terminate() + self.frontend_process.wait(timeout=5) + self.print_success("Frontend server stopped") + except Exception as e: + self.print_warning(f"Error stopping frontend: {str(e)}") + + # Terminate backend + if self.backend_process and self.backend_process.poll() is None: + try: + if self.is_windows: + # On Windows, use taskkill to terminate process tree + subprocess.run( + ['taskkill', '/F', '/T', '/PID', str(self.backend_process.pid)], + capture_output=True + ) + else: + self.backend_process.terminate() + self.backend_process.wait(timeout=5) + self.print_success("Backend server stopped") + except Exception as e: + self.print_warning(f"Error stopping backend: {str(e)}") + + self.print_success("All services stopped successfully") + + def run(self): + """Main run method""" + self.print_banner() + + # Pre-flight checks + self.print_info("Running pre-flight checks...") + + if not self.check_node_installed(): + return 1 + + if not self.check_npm_installed(): + return 1 + + if not self.check_dependencies_installed(): + self.print_warning("Please run 'npm install' first") + return 1 + + if not self.check_env_file(): + self.print_warning("Please configure .env file first") + return 1 + + self.print_success("All pre-flight checks passed!\n") + + # Start services + if not self.start_backend(): + self.cleanup() + return 1 + + time.sleep(2) # Give backend time to start + + if not self.start_frontend(): + self.cleanup() + return 1 + + # Monitor processes + try: + self.monitor_processes() + finally: + self.cleanup() + + return 0 + +def main(): + """Main entry point""" + launcher = AppLauncher() + + try: + sys.exit(launcher.run()) + except Exception as e: + print(f"\n{Color.FAIL}[FATAL ERROR]{Color.ENDC} {str(e)}") + launcher.cleanup() + sys.exit(1) + +if __name__ == '__main__': + main() diff --git a/package.json b/package.json index 17ca934..3c7cbbf 100644 --- a/package.json +++ b/package.json @@ -4,6 +4,7 @@ "description": "5 Why Root Cause Analysis Tool with Ollama API Integration", "type": "module", "scripts": { + "start": "python app.py", "dev": "concurrently \"npm run server\" \"npm run client\"", "server": "node server.js", "client": "vite", diff --git a/start.bat b/start.bat new file mode 100644 index 0000000..43af9ca --- /dev/null +++ b/start.bat @@ -0,0 +1,24 @@ +@echo off +REM 5 Why Root Cause Analyzer - Windows Launcher +REM Version: 1.0.0 + +echo. +echo ====================================================================== +echo 5 Why Root Cause Analyzer - v1.0.0 +echo Starting application... +echo ====================================================================== +echo. + +REM Check if Python is installed +python --version >nul 2>&1 +if %errorlevel% neq 0 ( + echo [ERROR] Python is not installed or not in PATH + echo Please install Python 3.7+ from https://www.python.org/ + pause + exit /b 1 +) + +REM Run the Python launcher +python app.py + +pause