karate_halloween/deploy/PM2_PRODUCTION_SETUP.md

Production Deployment & PM2 Setup Guide

Target Host / Domain: karate.ph.sokaris.link
Web Server: Nginx
Execution User: www-data
Port: 34822
Git Repository: https://dep.sokaris.link/vasily/karate_halloween.git

---

1. Directory Structure & Permissions

Recommended app directory on the server: /srv/apps/karate_halloween

# Create directory and clone repository (or set ownership)
sudo mkdir -p /srv/apps/karate_halloween
sudo git clone https://dep.sokaris.link/vasily/karate_halloween.git /srv/apps/karate_halloween

# Ensure ownership belongs to www-data
sudo chown -R www-data:www-data /srv/apps/karate_halloween
sudo chmod -R 775 /srv/apps/karate_halloween

---

2. Environment Variables Configuration

Create /srv/apps/karate_halloween/.env.local:

sudo -u www-data nano /srv/apps/karate_halloween/.env.local

Example content:

# Production Environment
NODE_ENV=production
PORT=34822

# 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:

cd /srv/apps/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:

sudo npm install -g pm2

Start the application with PM2 as www-data:

sudo -u www-data pm2 start /srv/apps/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:

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:

# Check status
sudo -u www-data pm2 status

# View live logs
sudo -u www-data pm2 logs karate_halloween

# Reload zero-downtime
sudo -u www-data pm2 reload karate_halloween

# Restart
sudo -u www-data pm2 restart karate_halloween

---

5. Nginx Configuration

Copy the provided Nginx configuration to sites-available:

sudo cp /srv/apps/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):

sudo certbot --nginx -d karate.ph.sokaris.link

Test and Reload Nginx:

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:

sudo -u www-data bash /srv/apps/karate_halloween/deploy/deploy.sh