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`

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

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

Example content:
```env
# 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`:

```bash
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:
```bash
sudo npm install -g pm2
```

### Start the application with PM2 as `www-data`:

```bash
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`:
```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 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`:

```bash
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):

```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 /srv/apps/karate_halloween/deploy/deploy.sh
```