@gv-sh/specgen-app 0.5.0 → 0.6.1

package/README.md

@@ -1,292 +1,320 @@
 # SpecGen App - Complete Platform
 
-[![Version](https://img.shields.io/badge/version-0.5.0-blue.svg)](https://github.com/gv-sh/specgen-app)
+[![Version](https://img.shields.io/badge/version-0.6.1-blue.svg)](https://github.com/gv-sh/specgen-app)
 
-A unified deployment package for the SpecGen speculative fiction generator platform.
+A unified deployment package for the SpecGen speculative fiction generator platform. **Optimized for port 8080 deployment with low memory usage.**
 
-## Components
+## 🚀 Quick Start
 
-- **Server**: Node.js API with OpenAI integration
-- **Admin**: React admin interface for content management
-- **User**: React user interface for story generation
+### One-Command Deployment (Recommended)
 
-## Quick Start
+```bash
+# Create project directory
+mkdir specgen && cd specgen
 
-### Using NPX (Recommended)
+# Deploy everything in one command
+npx @gv-sh/specgen-app deploy
+```
 
-```bash
-# Create and enter your project directory
-mkdir specgen-project
-cd specgen-project
+**What this does:**
+- Downloads and sets up server, admin, and user components
+- Builds React frontends optimized for production
+- Configures everything for port 8080
+- Starts with PM2 for process management
+- Prompts for OpenAI API key
 
-# Run setup directly with npx
-npx @gv-sh/specgen-app setup
+## 🌐 Access URLs
 
-# Start in development mode
-npx @gv-sh/specgen-app dev
+Once deployed, access your application at:
 
-# Or start in production mode
-npx @gv-sh/specgen-app production
-```
+- **Main Application**: http://your-server:8080/
+- **User Interface**: http://your-server:8080/app  
+- **Admin Panel**: http://your-server:8080/admin
+- **API Documentation**: http://your-server:8080/api-docs
+- **Health Check**: http://your-server:8080/api/health
+- **API Endpoints**: http://your-server:8080/api/*
+
+## 🖥️ Server Requirements
 
-### Low Memory Mode for Small Servers
+### Minimum Requirements
+- **Node.js**: 20.0.0 or higher
+- **RAM**: 1GB minimum (2GB recommended)
+- **Storage**: 2GB free space
+- **OS**: Ubuntu 20.04+ (or similar Linux distribution)
 
-If you're deploying on a small EC2 instance or any server with limited RAM:
+### Quick Server Setup (Ubuntu)
 
 ```bash
-# First, add swap space to prevent out-of-memory errors
-sudo fallocate -l 2G /swapfile
-sudo chmod 600 /swapfile
-sudo mkswap /swapfile
-sudo swapon /swapfile
-echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
+# Install Node.js 20+
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt-get install -y nodejs
 
-# Then use the low-memory versions of the commands
-npx @gv-sh/specgen-app setup-low-memory
-npx @gv-sh/specgen-app production-low-memory
+# Verify installation
+node --version  # Should show v20.x.x or higher
+npm --version
 ```
 
-### Using NPM Scripts
+## 📋 Deployment Methods
 
-1. **Setup**:
-   ```bash
-   npm run setup
-   ```
-   During setup, you'll be prompted to enter your OpenAI API key.
+### Method 1: Direct NPX Deployment (Easiest)
 
-2. **Add OpenAI API Key** to `server/.env` if you skipped during setup
+```bash
+# SSH into your server
+ssh -i "your-key.pem" ubuntu@your-server-ip
+
+# Create project and deploy
+mkdir specgen && cd specgen
+npx @gv-sh/specgen-app deploy
+```
 
-3. **Start Development**:
-   ```bash
-   npm run dev
-   ```
+### Method 2: Development Mode
 
-4. **Start Production** (optimized build with API key validation):
-   ```bash
-   npm run production
-   ```
+For local development with separate ports:
 
-## Access URLs
+```bash
+mkdir specgen-dev && cd specgen-dev
+npx @gv-sh/specgen-app setup
+npx @gv-sh/specgen-app dev
+```
 
+**Development URLs:**
 - User Interface: http://localhost:3002
-- Admin Interface: http://localhost:3001
-- API: http://localhost:3000
-
-## Deployment Options
-
-### Option 1: Quick NPX Deployment to Remote Server
-
-If you have SSH access to a server (like an EC2 instance), this is the fastest way to deploy:
-
-1. **Save your SSH key** to a file (e.g., `key.pem`) and set permissions:
-   ```bash
-   chmod 400 key.pem
-   ```
-
-2. **SSH into your server**:
-   ```bash
-   ssh -i "key.pem" ubuntu@your-server-ip
-   ```
-
-3. **Install Node.js 18 or higher**:
-   ```bash
-   curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
-   sudo apt-get install -y nodejs
-   ```
-
-4. **Install and run SpecGen**:
-   ```bash
-   # Add swap space to prevent out-of-memory errors
-   sudo fallocate -l 2G /swapfile
-   sudo chmod 600 /swapfile
-   sudo mkswap /swapfile
-   sudo swapon /swapfile
-   echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
-   
-   # Create and enter project directory
-   mkdir specgen
-   cd specgen
-   
-   # Run the setup with low memory optimization
-   npx @gv-sh/specgen-app setup-low-memory
-   
-   # Start in production mode with low memory optimization
-   npx @gv-sh/specgen-app production-low-memory
-   ```
-
-5. **Keep the service running with PM2** (recommended):
-   ```bash
-   sudo npm install -g pm2
-   # Use the low-memory production mode with PM2
-   pm2 start "npx @gv-sh/specgen-app production-low-memory" --name "specgen"
-   pm2 startup
-   pm2 save
-   ```
-
-6. **Access your application**:
-   - User Interface: http://your-server-ip:3002
-   - Admin Interface: http://your-server-ip:3001
-   - API: http://your-server-ip:3000
-
-### Option 2: Global NPM Package Deployment
-
-#### Local Machine Deployment
-
-1. **Install globally** (recommended for deployment):
-   ```bash
-   npm install -g @gv-sh/specgen-app
-   ```
-
-2. **Create a project directory**:
-   ```bash
-   mkdir specgen-project
-   cd specgen-project
-   ```
-
-3. **Initialize and setup**:
-   ```bash
-   specgen-app setup
-   ```
-   During setup, you'll be prompted to enter your OpenAI API key.
-
-4. **Start the application**:
-   - Development mode: `specgen-app dev`
-   - Production mode: `specgen-app production`
-
-#### Remote Server Deployment
-
-1. **SSH into your server**:
-   ```bash
-   ssh -i "your-key.pem" username@your-server
-   ```
-
-2. **Install Node.js** (if not already installed):
-   ```bash
-   curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
-   sudo apt-get install -y nodejs
-   ```
-
-3. **Create a project directory**:
-   ```bash
-   mkdir specgen
-   cd specgen
-   ```
-
-4. **Install SpecGen globally**:
-   ```bash
-   npm install -g @gv-sh/specgen-app
-   ```
-
-5. **Setup the application**:
-   ```bash
-   specgen-app setup
-   ```
-
-6. **Start in production mode**:
-   ```bash
-   specgen-app production
-   ```
-
-### Option 3: Manual Deployment
-
-Alternatively, you can deploy manually using the repository:
-
-#### Build and Run Locally
+- Admin Interface: http://localhost:3001  
+- API Server: http://localhost:8080
+
+### Method 3: Manual Deployment
+
+If you prefer more control:
+
 ```bash
+# Clone repository
 git clone https://github.com/gv-sh/specgen-app.git
 cd specgen-app
+
+# Setup and deploy
 npm run setup
-npm run build
-npm run production
+npm run deploy
 ```
 
-#### AWS Deployment Script
+## 🔧 Configuration
+
+### OpenAI API Key Setup
 
-1. Launch Ubuntu 22.04 instance with SSH access
-2. Run deployment script:
+During deployment, you'll be prompted for your OpenAI API key. You can also set it manually:
 
 ```bash
-# On AWS instance
-wget https://github.com/gv-sh/specgen-app/raw/main/scripts/deploy.sh
-chmod +x deploy.sh
-sudo ./deploy.sh
+# Create/edit the environment file
+echo "OPENAI_API_KEY=your_openai_api_key_here" > server/.env
+echo "NODE_ENV=production" >> server/.env
+echo "PORT=8080" >> server/.env
+
+# Restart the service
+npx pm2 restart specgen --update-env
 ```
 
-## Management Commands
+### Environment Variables
+
+The deployment creates these configuration files:
+- `server/.env` - Server configuration (port 8080, API key)
+- `admin/.env.development` - Admin development settings  
+- `user/.env.development` - User development settings
+
+## 📊 Process Management
+
+The deployment uses PM2 for process management:
 
-When using NPX or global installation:
 ```bash
 # Check status
-npx @gv-sh/specgen-app deploy:status
-# or when installed globally
-specgen-app deploy:status
-
-# Stop services
-npx @gv-sh/specgen-app deploy:stop
-# or
-specgen-app deploy:stop
-
-# Restart services
-npx @gv-sh/specgen-app deploy:restart
-# or
-specgen-app deploy:restart
-
-# Update to latest version
-npm update -g @gv-sh/specgen-app
+npx pm2 status
+
+# View logs  
+npx pm2 logs specgen
+
+# Restart application
+npx pm2 restart specgen
+
+# Stop application
+npx pm2 stop specgen
+
+# Monitor resources
+npx pm2 monit
 ```
 
-When using the repository:
+## 🔍 Troubleshooting
+
+### Common Issues and Solutions
+
+#### 1. Port 8080 Already in Use
 ```bash
-# Stop services
-npm run deploy:stop
+# Check what's using the port
+sudo lsof -i :8080
 
-# Restart services
-npm run deploy:restart
+# Kill the process
+sudo lsof -ti:8080 | xargs kill -9
 
-# Update to latest
-npm run deploy:update
+# Redeploy
+npx @gv-sh/specgen-app deploy
+```
 
-# Check status
-npm run deploy:status
+#### 2. Frontend Not Loading (404 Errors)
+```bash
+# Check if builds exist
+ls -la admin/build/
+ls -la user/build/
+
+# If missing, manually rebuild
+cd admin && npm install && GENERATE_SOURCEMAP=false PUBLIC_URL=/admin npm run build
+cd ../user && npm install && GENERATE_SOURCEMAP=false REACT_APP_API_URL=/api PUBLIC_URL=/app npm run build
 
-# Create backup
-npm run deploy:backup
+# Restart server
+npx pm2 restart specgen
 ```
 
-## Available Commands
+#### 3. OpenAI API Key Issues
+```bash
+# Check current environment
+npx pm2 env 0
+
+# Update API key
+echo "OPENAI_API_KEY=your_new_key_here" > server/.env
+echo "NODE_ENV=production" >> server/.env
+echo "PORT=8080" >> server/.env
+
+# Restart with new environment
+npx pm2 restart specgen --update-env
+```
+
+#### 4. Out of Memory Errors
+```bash
+# Add swap space (2GB recommended)
+sudo fallocate -l 2G /swapfile
+sudo chmod 600 /swapfile
+sudo mkswap /swapfile
+sudo swapon /swapfile
+echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
+
+# Verify swap is active
+free -h
+```
+
+#### 5. Node.js Version Issues
+```bash
+# Check current version
+node --version
+
+# If less than v20, update:
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt-get install -y nodejs
+```
+
+### Debugging Commands
+
+```bash
+# Test API health
+curl http://localhost:8080/api/health
+
+# Test main page response
+curl -I http://localhost:8080/
 
-The following commands are available when using `npx @gv-sh/specgen-app` or `specgen-app` (if installed globally):
+# Check server logs
+npx pm2 logs specgen --lines 50
 
-- `setup` - Set up the SpecGen application
-- `setup-low-memory` - Set up the SpecGen application with memory optimizations
-- `production` - Run the application in production mode
-- `production-low-memory` - Run the application in production mode with memory optimizations
-- `dev` - Run the application in development mode
-- `deploy` - Deploy the application
-- `deploy:stop` - Stop the deployed application
-- `deploy:restart` - Restart the deployed application
-- `deploy:update` - Update the deployed application
-- `deploy:status` - Check the status of the deployed application
-- `deploy:backup` - Create a backup of the deployed application
-- `troubleshoot` - Run troubleshooting checks
+# Check build status
+ls -la */build/ 2>/dev/null || echo "No builds found"
 
-## Troubleshooting
+# Check processes listening on port 8080
+sudo netstat -tlnp | grep :8080
+```
 
-If you encounter issues:
+### Manual Build Process
+
+If automatic builds fail, try manual building:
 
 ```bash
-# Using npx
-npx @gv-sh/specgen-app troubleshoot
+# Stop current deployment
+npx pm2 stop specgen
+
+# Manual server setup
+npm pack @gv-sh/specgen-server
+tar -xzf gv-sh-specgen-server-*.tgz
+mv package server
+cd server && npm install && cd ..
+
+# Manual admin build
+npm pack @gv-sh/specgen-admin  
+tar -xzf gv-sh-specgen-admin-*.tgz
+mv package admin
+cd admin && npm install && GENERATE_SOURCEMAP=false PUBLIC_URL=/admin npm run build && cd ..
+
+# Manual user build
+npm pack @gv-sh/specgen-user
+tar -xzf gv-sh-specgen-user-*.tgz  
+mv package user
+cd user && npm install && GENERATE_SOURCEMAP=false REACT_APP_API_URL=/api PUBLIC_URL=/app npm run build && cd ..
+
+# Restart deployment
+npx pm2 start server/index.js --name specgen
+```
+
+## 🚨 Known Issues
+
+### Current Limitations
+- **Memory Usage**: Requires at least 1GB RAM for builds
+- **Build Time**: Initial deployment can take 5-10 minutes
+- **SQLite Dependencies**: May require build tools on some systems
+- **Static File Serving**: Builds must complete successfully for frontend access
+
+### AWS EC2 Specific
+- **Security Groups**: Ensure port 8080 is open in your security group
+- **Instance Type**: t2.micro may struggle with builds (t2.small recommended)
+- **Storage**: Ensure at least 2GB free space for node_modules and builds
+
+## 📚 API Documentation
+
+Once deployed, access interactive API documentation at:
+- **Swagger UI**: http://your-server:8080/api-docs
 
-# Using global installation
-specgen-app troubleshoot
+### Key API Endpoints
+- `GET /api/health` - Health check and system status
+- `POST /api/generate` - Generate speculative fiction content
+- `GET /api/categories` - List available story categories
+- `GET /api/parameters` - Get generation parameters
 
-# For repository installation
-npm run troubleshoot
+## 🔄 Updates and Maintenance
+
+### Updating SpecGen
+```bash
+# Stop current deployment
+npx pm2 stop specgen
+
+# Clean up old installation
+rm -rf admin user server node_modules
+
+# Deploy latest version
+npx @gv-sh/specgen-app deploy
 ```
 
-This will check your setup and identify common problems.
+### Backup Important Data
+```bash
+# Backup database and configurations
+tar -czf specgen-backup-$(date +%Y%m%d).tar.gz server/data server/.env logs/
+```
+
+## 🤝 Support
+
+### Getting Help
+- **Health Check**: Visit http://your-server:8080/api/health
+- **Logs**: Run `npx pm2 logs specgen`
+- **Issues**: [GitHub Issues](https://github.com/gv-sh/specgen-app/issues)
+- **Status**: Run `npx pm2 status` to check process status
+
+### Reporting Bugs
+When reporting issues, please include:
+- Output of `npx pm2 logs specgen`
+- Output of `curl http://localhost:8080/api/health`
+- Your server specifications (RAM, OS version, Node.js version)
+- Any error messages from the deployment process
 
-## Environment Variables
+## 📄 License
 
-The setup script creates necessary environment files automatically. You only need to add your OpenAI API key during setup or later to `server/.env`.
+This project is licensed under the ISC License.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gv-sh/specgen-app",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Complete SpecGen application with server, admin, and user interfaces",
   "main": "index.js",
   "bin": {
@@ -8,20 +8,15 @@
   },
   "scripts": {
     "setup": "chmod +x scripts/setup.sh && ./scripts/setup.sh",
-    "setup-low-memory": "chmod +x scripts/setup-low-memory.sh && ./scripts/setup-low-memory.sh",
     "dev": "chmod +x scripts/dev.sh && ./scripts/dev.sh",
     "build": "cd admin && npm run build && cd ../user && npm run build",
     "start": "cd server && npm start",
     "production": "chmod +x scripts/production.sh && ./scripts/production.sh",
-    "production-low-memory": "chmod +x scripts/production-low-memory.sh && ./scripts/production-low-memory.sh",
-    "make-executable": "chmod +x scripts/make-executable.sh && ./scripts/make-executable.sh",
     "deploy": "chmod +x scripts/deploy.sh && ./scripts/deploy.sh",
+    "make-executable": "chmod +x scripts/make-executable.sh && ./scripts/make-executable.sh",
     "deploy:stop": "chmod +x scripts/stop.sh && ./scripts/stop.sh",
     "deploy:restart": "chmod +x scripts/restart.sh && ./scripts/restart.sh",
-    "deploy:update": "chmod +x scripts/update.sh && ./scripts/update.sh",
     "deploy:status": "chmod +x scripts/status.sh && ./scripts/status.sh",
-    "deploy:backup": "chmod +x scripts/backup.sh && ./scripts/backup.sh",
-    "troubleshoot": "chmod +x scripts/troubleshoot.sh && ./scripts/troubleshoot.sh",
     "postinstall": "chmod +x bin/cli.js"
   },
   "dependencies": {

package/scripts/deploy-8080.sh.bak

@@ -0,0 +1,104 @@
+#!/bin/bash
+
+# SpecGen Deploy Script - Port 8080 Production Deployment
+set -e
+
+echo "🚀 Deploying SpecGen to production on port 8080..."
+
+# Function to check if port is available
+check_port() {
+    local port=$1
+    if lsof -Pi :$port -sTCP:LISTEN -t >/dev/null 2>&1; then
+        return 1  # Port in use
+    else
+        return 0  # Port available
+    fi
+}
+
+# Stop existing PM2 processes
+echo "Stopping existing PM2 processes..."
+npx pm2 stop all 2>/dev/null || true
+npx pm2 delete all 2>/dev/null || true
+
+# Kill any processes on port 8080
+echo "Freeing port 8080..."
+if ! check_port 8080; then
+    echo "Port 8080 is in use. Attempting to free it..."
+    lsof -ti:8080 | xargs kill -9 2>/dev/null || true
+    sleep 2
+fi
+
+# Run the production setup
+echo "Running production setup..."
+npm run production-low-memory &
+SETUP_PID=$!
+
+# Wait for setup to complete or timeout
+TIMEOUT=60
+COUNT=0
+while [ $COUNT -lt $TIMEOUT ]; do
+    if ! kill -0 $SETUP_PID 2>/dev/null; then
+        echo "Production setup completed"
+        break
+    fi
+    sleep 1
+    COUNT=$((COUNT + 1))
+done
+
+# Kill setup process if it's still running
+if kill -0 $SETUP_PID 2>/dev/null; then
+    echo "Setup taking too long, continuing with PM2 deployment..."
+    kill $SETUP_PID 2>/dev/null || true
+fi
+
+# Wait a moment for cleanup
+sleep 2
+
+# Create PM2 ecosystem configuration
+echo "Creating PM2 ecosystem configuration..."
+cat > ecosystem.config.js << 'EOF'
+module.exports = {
+  apps: [{
+    name: 'specgen',
+    script: './server/index.js',
+    cwd: process.cwd(),
+    env: {
+      NODE_ENV: 'production',
+      PORT: 8080
+    },
+    instances: 1,
+    exec_mode: 'fork',
+    max_memory_restart: '500M',
+    error_file: './logs/err.log',
+    out_file: './logs/out.log',
+    log_file: './logs/combined.log',
+    time: true,
+    watch: false,
+    ignore_watch: ['node_modules', 'logs', '*.log']
+  }]
+}
+EOF
+
+# Create logs directory
+mkdir -p logs
+
+# Start with PM2
+echo "Starting SpecGen with PM2 on port 8080..."
+NODE_ENV=production PORT=8080 npx pm2 start ecosystem.config.js
+
+# Wait for startup
+sleep 5
+
+echo ""
+echo "✅ SpecGen deployment completed!"
+echo ""
+echo "🌐 Access your application at:"
+echo "   - Main page: http://$(curl -s ifconfig.me 2>/dev/null || echo 'your-server'):8080/"
+echo "   - User app: http://$(curl -s ifconfig.me 2>/dev/null || echo 'your-server'):8080/app"
+echo "   - Admin panel: http://$(curl -s ifconfig.me 2>/dev/null || echo 'your-server'):8080/admin"
+echo "   - API docs: http://$(curl -s ifconfig.me 2>/dev/null || echo 'your-server'):8080/api-docs"
+echo "   - Health check: http://$(curl -s ifconfig.me 2>/dev/null || echo 'your-server'):8080/api/health"
+echo ""
+echo "📊 Check status with: npx pm2 status"
+echo "📝 View logs with: npx pm2 logs specgen"
+echo "🔄 Restart with: npx pm2 restart specgen"