docs: add PM2 and Nginx prod setup for karate.ph.sokaris.link with www-data

deploy/PM2_PRODUCTION_SETUP.md

@@ -0,0 +1,131 @@
+# Production Deployment & PM2 Setup Guide
+
+Target Host / Domain: **`karate.ph.sokaris.link`**  
+Web Server: **Nginx**  
+Execution User: **`www-data`**  
+Port: **`34821`**  
+Git Repository: **`https://dep.sokaris.link/vasily/karate_halloween.git`**
+
+---
+
+## 1. Directory Structure & Permissions
+
+Recommended app directory on the server: `/var/www/karate_halloween`
+
+```bash
+# Create directory and clone repository (or set ownership)
+sudo mkdir -p /var/www/karate_halloween
+sudo git clone https://dep.sokaris.link/vasily/karate_halloween.git /var/www/karate_halloween
+
+# Ensure ownership belongs to www-data
+sudo chown -R www-data:www-data /var/www/karate_halloween
+sudo chmod -R 775 /var/www/karate_halloween
+```
+
+---
+
+## 2. Environment Variables Configuration
+
+Create `/var/www/karate_halloween/.env.local`:
+
+```bash
+sudo -u www-data nano /var/www/karate_halloween/.env.local
+```
+
+Example content:
+```env
+# Production Environment
+NODE_ENV=production
+PORT=34821
+
+# AI API Keys
+GEMINI_API_KEY=your_gemini_api_key_here
+OPENROUTER_API_KEY=your_openrouter_api_key_here
+GENERATION_MODEL=nanobanana 2
+```
+
+---
+
+## 3. Install Dependencies & Build
+
+Run as `www-data`:
+
+```bash
+cd /var/www/karate_halloween
+sudo -u www-data npm ci
+sudo -u www-data npm run build
+```
+
+---
+
+## 4. PM2 Setup for User `www-data`
+
+Install PM2 globally if not already installed:
+```bash
+sudo npm install -g pm2
+```
+
+### Start the application with PM2 as `www-data`:
+
+```bash
+sudo -u www-data pm2 start /var/www/karate_halloween/ecosystem.config.cjs
+sudo -u www-data pm2 save
+```
+
+### Configure PM2 Startup on Boot for `www-data`:
+
+Generate the systemd service for user `www-data`:
+```bash
+sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u www-data --hp /var/www
+```
+*(Copy and run the exact command output by `pm2 startup` if different).*
+
+### Useful PM2 Management Commands:
+
+```bash
+# Check status
+sudo -u www-data pm2 status
+
+# View live logs
+sudo -u www-data pm2 logs photobooth_web_v1
+
+# Reload zero-downtime
+sudo -u www-data pm2 reload photobooth_web_v1
+
+# Restart
+sudo -u www-data pm2 restart photobooth_web_v1
+```
+
+---
+
+## 5. Nginx Configuration
+
+Copy the provided Nginx configuration to `sites-available`:
+
+```bash
+sudo cp /var/www/karate_halloween/deploy/karate.ph.sokaris.link.conf /etc/nginx/sites-available/karate.ph.sokaris.link.conf
+sudo ln -sf /etc/nginx/sites-available/karate.ph.sokaris.link.conf /etc/nginx/sites-enabled/
+```
+
+### Obtain SSL Certificate (Let's Encrypt / Certbot):
+
+```bash
+sudo certbot --nginx -d karate.ph.sokaris.link
+```
+
+### Test and Reload Nginx:
+
+```bash
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+---
+
+## 6. Automated Deployments (`deploy/deploy.sh`)
+
+Whenever you push new updates to git, deploy on the server with:
+
+```bash
+sudo -u www-data bash /var/www/karate_halloween/deploy/deploy.sh
+```