@gv-sh/specgen-app 0.4.0 → 0.5.1

package/README.md

@@ -1,14 +1,21 @@
 # SpecGen App - Complete Platform
 
-[![Version](https://img.shields.io/badge/version-0.4.0-blue.svg)](https://github.com/gv-sh/specgen-app)
+[![Version](https://img.shields.io/badge/version-0.5.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. **Now optimized for low-memory servers and unified on port 8080!**
+
+## 🚀 What's New
+
+- **Single Port Deployment**: Everything runs on port 8080 with clean URL paths
+- **Low Memory Default**: Optimized for small servers and EC2 instances
+- **Automatic Cleanup**: Smart setup that cleans existing installations
+- **Unified Interface**: All services accessible through one port
 
 ## Components
 
-- **Server**: Node.js API with OpenAI integration
-- **Admin**: React admin interface for content management
-- **User**: React user interface for story generation
+- **Server**: Node.js API with OpenAI integration (Port 8080)
+- **Admin**: React admin interface at `/admin`
+- **User**: React user interface at `/app` (also default at `/`)
 
 ## Quick Start
 
@@ -19,247 +26,238 @@ A unified deployment package for the SpecGen speculative fiction generator platf
 mkdir specgen-project
 cd specgen-project
 
-# Run setup directly with npx
+# Run setup (automatically includes low-memory optimizations and cleanup)
 npx @gv-sh/specgen-app setup
 
-# Start in development mode
+# Start in development mode (traditional separate ports)
 npx @gv-sh/specgen-app dev
 
-# Or start in production mode
+# Or start in production mode (unified port 8080)
 npx @gv-sh/specgen-app production
-```
-
-### Using NPM Scripts
-
-1. **Setup**:
-   ```bash
-   npm run setup
-   ```
-   During setup, you'll be prompted to enter your OpenAI API key.
-
-2. **Add OpenAI API Key** to `server/.env` if you skipped during setup
-
-3. **Start Development**:
-   ```bash
-   npm run dev
-   ```
 
-4. **Start Production** (optimized build with API key validation):
-   ```bash
-   npm run production
-   ```
+# Or deploy with PM2 (recommended for servers)
+npx @gv-sh/specgen-app deploy
+```
 
-## Access URLs
+## 🌐 Access URLs
 
-- User Interface: http://localhost:3002
-- Admin Interface: http://localhost:3001
-- API: http://localhost:3000
+### Production Mode (Port 8080 - Unified)
+- **Main Application**: http://localhost:8080/
+- **User Interface**: http://localhost:8080/app
+- **Admin Panel**: http://localhost:8080/admin
+- **API Documentation**: http://localhost:8080/api-docs
+- **Health Check**: http://localhost:8080/api/health
+- **API Endpoints**: http://localhost:8080/api/*
 
-## Deployment Options
+### Development Mode (Separate Ports)
+- **User Interface**: http://localhost:3002
+- **Admin Interface**: http://localhost:3001
+- **API Server**: http://localhost:8080
 
-### Option 1: Quick NPX Deployment to Remote Server
+## 🖥️ Server Deployment
 
-If you have SSH access to a server (like an EC2 instance), this is the fastest way to deploy:
+### Option 1: Quick AWS/VPS Deployment
 
-1. **Save your SSH key** to a file (e.g., `key.pem`) and set permissions:
-   ```bash
-   chmod 400 key.pem
-   ```
+Perfect for EC2, DigitalOcean, or any Ubuntu server:
 
-2. **SSH into your server**:
+1. **SSH into your server**:
    ```bash
    ssh -i "key.pem" ubuntu@your-server-ip
    ```
 
-3. **Install Node.js 18 or higher**:
+2. **Install Node.js 20+** (required):
    ```bash
-   curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+   curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
    sudo apt-get install -y nodejs
    ```
 
-4. **Install and run SpecGen**:
+3. **Deploy SpecGen** (one command setup with cleanup):
    ```bash
-   # Create and enter project directory
-   mkdir specgen
-   cd specgen
-   
-   # Run the setup
+   mkdir specgen && cd specgen
    npx @gv-sh/specgen-app setup
-   
-   # Start in production mode
-   npx @gv-sh/specgen-app production
+   npx @gv-sh/specgen-app deploy
    ```
 
-5. **Keep the service running with PM2** (recommended):
-   ```bash
-   sudo npm install -g pm2
-   pm2 start "npx @gv-sh/specgen-app production" --name "specgen"
-   pm2 startup
-   pm2 save
-   ```
+4. **Access your application**:
+   - **Main**: http://your-server-ip:8080/
+   - **User App**: http://your-server-ip:8080/app
+   - **Admin Panel**: http://your-server-ip:8080/admin
 
-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: Manual Setup
 
-### Option 2: Global NPM Package Deployment
+```bash
+# Clone and setup manually
+git clone https://github.com/gv-sh/specgen-app.git
+cd specgen-app
+npm run setup
+npm run deploy
+```
 
-#### Local Machine Deployment
+## 🛠️ Setup Features
 
-1. **Install globally** (recommended for deployment):
-   ```bash
-   npm install -g @gv-sh/specgen-app
-   ```
+The setup script now includes **comprehensive cleanup**:
 
-2. **Create a project directory**:
-   ```bash
-   mkdir specgen-project
-   cd specgen-project
-   ```
+- ✅ **PM2 Process Cleanup**: Stops and removes existing PM2 processes
+- ✅ **Port Liberation**: Frees up ports 8080, 3000, 3001, 3002
+- ✅ **Nginx Cleanup**: Removes conflicting nginx configurations
+- ✅ **Docker Cleanup**: Removes any existing SpecGen containers
+- ✅ **Service Cleanup**: Removes systemd services
+- ✅ **File Cleanup**: Removes old installations and log files
+- ✅ **Low Memory Optimization**: Optimized for servers with limited RAM
 
-3. **Initialize and setup**:
-   ```bash
-   specgen-app setup
-   ```
-   During setup, you'll be prompted to enter your OpenAI API key.
+## 📋 Available Commands
 
-4. **Start the application**:
-   - Development mode: `specgen-app dev`
-   - Production mode: `specgen-app production`
+### Core Commands
+```bash
+# Setup with cleanup (one-time)
+npx @gv-sh/specgen-app setup
 
-#### Remote Server Deployment
+# Development mode (separate ports)
+npx @gv-sh/specgen-app dev
 
-1. **SSH into your server**:
-   ```bash
-   ssh -i "your-key.pem" username@your-server
-   ```
+# Production mode (direct run on port 8080)
+npx @gv-sh/specgen-app production
 
-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
-   ```
+# Production deployment with PM2 (recommended)
+npx @gv-sh/specgen-app deploy
+```
 
-3. **Create a project directory**:
-   ```bash
-   mkdir specgen
-   cd specgen
-   ```
+### Management Commands
+```bash
+# Check deployment status
+npx @gv-sh/specgen-app deploy:status
 
-4. **Install SpecGen globally**:
-   ```bash
-   npm install -g @gv-sh/specgen-app
-   ```
+# Stop all services
+npx @gv-sh/specgen-app deploy:stop
 
-5. **Setup the application**:
-   ```bash
-   specgen-app setup
-   ```
+# Restart services
+npx @gv-sh/specgen-app deploy:restart
+```
 
-6. **Start in production mode**:
-   ```bash
-   specgen-app production
-   ```
+### Using NPM Scripts (if you cloned the repo)
+```bash
+npm run setup      # Setup with cleanup
+npm run dev        # Development mode
+npm run production # Production mode
+npm run deploy     # Deploy with PM2
+```
 
-### Option 3: Manual Deployment
+## 🔧 Configuration
 
-Alternatively, you can deploy manually using the repository:
+### OpenAI API Key
+You'll be prompted for your OpenAI API key during setup. If you skip it, add it later to `server/.env`:
 
-#### Build and Run Locally
-```bash
-git clone https://github.com/gv-sh/specgen-app.git
-cd specgen-app
-npm run setup
-npm run build
-npm run production
+```env
+OPENAI_API_KEY=your_openai_api_key_here
+NODE_ENV=production
+PORT=8080
 ```
 
-#### AWS Deployment Script
+### Environment Files
+The setup automatically creates optimized environment files:
+- `server/.env` - Server configuration (port 8080)
+- `admin/.env.development` - Admin dev settings
+- `user/.env.development` - User dev settings
+
+## 🐳 Docker Alternative
 
-1. Launch Ubuntu 22.04 instance with SSH access
-2. Run deployment script:
+If you prefer Docker:
 
 ```bash
-# On AWS instance
-wget https://github.com/gv-sh/specgen-app/raw/main/scripts/deploy.sh
-chmod +x deploy.sh
-sudo ./deploy.sh
+# Quick Docker setup
+docker run -d \
+  --name specgen \
+  -p 8080:8080 \
+  -e OPENAI_API_KEY=your_key_here \
+  gvsh/specgen-app:latest
 ```
 
-## Management Commands
+## 📊 Management with PM2
+
+When deployed with `npm run deploy`, you get PM2 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
+npx pm2 status
 
-# Stop services
-npx @gv-sh/specgen-app deploy:stop
-# or
-specgen-app deploy:stop
+# View logs
+npx pm2 logs specgen
 
-# Restart services
-npx @gv-sh/specgen-app deploy:restart
-# or
-specgen-app deploy:restart
+# Restart
+npx pm2 restart specgen
+
+# Stop
+npx pm2 stop specgen
 
-# Update to latest version
-npm update -g @gv-sh/specgen-app
+# Monitor
+npx pm2 monit
 ```
 
-When using the repository:
-```bash
-# Stop services
-npm run deploy:stop
+## 🔍 Troubleshooting
 
-# Restart services
-npm run deploy:restart
+### Common Issues
 
-# Update to latest
-npm run deploy:update
+1. **Port 8080 Already in Use**:
+   ```bash
+   # The setup script handles this automatically, but if needed:
+   sudo lsof -ti:8080 | xargs kill -9
+   ```
 
-# Check status
-npm run deploy:status
+2. **Out of Memory on Small Servers**:
+   ```bash
+   # Add swap space (setup script suggests this)
+   sudo fallocate -l 2G /swapfile
+   sudo chmod 600 /swapfile
+   sudo mkswap /swapfile
+   sudo swapon /swapfile
+   ```
 
-# Create backup
-npm run deploy:backup
-```
+3. **Node.js Version Issues**:
+   ```bash
+   # Ensure Node.js 20+ is installed
+   node --version  # Should be v20+
+   ```
+
+4. **SQLite3 Binding Errors**:
+   ```bash
+   # The setup script includes engine-strict=false
+   # If issues persist, run setup again - it includes full cleanup
+   npx @gv-sh/specgen-app setup
+   ```
 
-## Available Commands
+### Health Check
+Test if your deployment is working:
+```bash
+curl http://localhost:8080/api/health
+# Should return: {"status":"ok","port":8080}
+```
 
-The following commands are available when using `npx @gv-sh/specgen-app` or `specgen-app` (if installed globally):
+## 🚨 Breaking Changes from Previous Versions
 
-- `setup` - Set up the SpecGen application
-- `production` - Run the application in production mode
-- `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
+- **Port Change**: Default port changed from 3000 → 8080
+- **URL Structure**: Admin at `/admin`, User at `/app`
+- **Simplified Scripts**: Single `setup` and `production` commands
+- **Automatic Cleanup**: Setup now cleans existing installations
 
-## Troubleshooting
+## 📚 API Documentation
 
-If you encounter issues:
+Once deployed, access the interactive API documentation at:
+- **Swagger UI**: http://your-server:8080/api-docs
 
-```bash
-# Using npx
-npx @gv-sh/specgen-app troubleshoot
+## 🤝 Contributing
 
-# Using global installation
-specgen-app troubleshoot
+1. Fork the repository
+2. Create your feature branch
+3. Commit your changes
+4. Push to the branch
+5. Create a Pull Request
 
-# For repository installation
-npm run troubleshoot
-```
+## 📄 License
 
-This will check your setup and identify common problems.
+This project is licensed under the ISC License.
 
-## Environment Variables
+## 🆘 Support
 
-The setup script creates necessary environment files automatically. You only need to add your OpenAI API key during setup or later to `server/.env`.
+- **Issues**: [GitHub Issues](https://github.com/gv-sh/specgen-app/issues)
+- **Documentation**: Check `/api-docs` when running
+- **Health Check**: Visit `/api/health` to verify installation

package/bin/cli.js

@@ -38,9 +38,15 @@ switch (command) {
   case 'setup':
     runScript('setup');
     break;
+  case 'setup-low-memory':
+    runScript('setup-low-memory');
+    break;
   case 'production':
     runScript('production');
     break;
+  case 'production-low-memory':
+    runScript('production-low-memory');
+    break;
   case 'dev':
     runScript('dev');
     break;
@@ -69,7 +75,9 @@ switch (command) {
     console.log('Usage: specgen-app <command>');
     console.log('\nAvailable commands:');
     console.log('  setup           - Set up the SpecGen application');
+  console.log('  setup-low-memory - Set up the SpecGen application with memory optimizations');
     console.log('  production      - Run the application in production mode');
+  console.log('  production-low-memory - Run the application in production mode with memory optimizations');
     console.log('  dev             - Run the application in development mode');
     console.log('  deploy          - Deploy the application');
     console.log('  deploy:stop     - Stop the deployed application');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gv-sh/specgen-app",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Complete SpecGen application with server, admin, and user interfaces",
   "main": "index.js",
   "bin": {
@@ -16,10 +16,7 @@
     "deploy": "chmod +x scripts/deploy.sh && ./scripts/deploy.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"