diff --git a/README.md b/README.md index f6ba7d0..9fc5323 100644 --- a/README.md +++ b/README.md @@ -96,6 +96,8 @@ cmd /c npm run build cmd /c npm start ``` +For production deployment instructions on Linux with **PM2**, **Nginx** (`karate.ph.sokaris.link`), and user **`www-data`**, see [`deploy/PM2_PRODUCTION_SETUP.md`](deploy/PM2_PRODUCTION_SETUP.md). + --- ## ⚙️ Configuration Guide diff --git a/deploy/PM2_PRODUCTION_SETUP.md b/deploy/PM2_PRODUCTION_SETUP.md new file mode 100644 index 0000000..9d03895 --- /dev/null +++ b/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 +``` diff --git a/deploy/karate.ph.sokaris.link.conf b/deploy/karate.ph.sokaris.link.conf new file mode 100644 index 0000000..3e20cf0 --- /dev/null +++ b/deploy/karate.ph.sokaris.link.conf @@ -0,0 +1,150 @@ +# /etc/nginx/sites-available/karate.ph.sokaris.link +# +# Production Nginx reverse proxy configuration for Karate Halloween Photo Booth +# Domain: karate.ph.sokaris.link +# Backend: Next.js PM2 process on 127.0.0.1:34821 +# User: www-data + +# Rate limiting zones (can be defined in http block in /etc/nginx/nginx.conf or here if http-level included) +limit_req_zone $binary_remote_addr zone=karate_api_limit:10m rate=10r/s; +limit_req_zone $binary_remote_addr zone=karate_auth_limit:10m rate=5r/m; + +upstream karate_backend { + server 127.0.0.1:34821; + keepalive 32; +} + +# HTTP: Redirect all traffic to HTTPS (and allow Let's Encrypt / Certbot challenges) +server { + listen 80; + listen [::]:80; + server_name karate.ph.sokaris.link; + + # Certbot challenge directory + location /.well-known/acme-challenge/ { + root /var/www/html; + } + + # Redirect all other HTTP traffic to HTTPS + location / { + return 301 https://$host$request_uri; + } +} + +# HTTPS: Secure proxy block +server { + listen 443 ssl http2; + listen [::]:443 ssl http2; + server_name karate.ph.sokaris.link; + + # SSL Certificates (Managed by Let's Encrypt / Certbot) + ssl_certificate /etc/letsencrypt/live/karate.ph.sokaris.link/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/karate.ph.sokaris.link/privkey.pem; + include /etc/letsencrypt/options-ssl-nginx.conf; + ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; + + # Maximum upload size for photo uploads (15MB) + client_max_body_size 15M; + + # Camera Access & Security Policy Headers + add_header Permissions-Policy "camera=(self), microphone=()" always; + add_header Feature-Policy "camera 'self'; microphone 'none'" always; + add_header X-Frame-Options "SAMEORIGIN" always; + add_header X-Content-Type-Options "nosniff" always; + add_header X-XSS-Protection "1; mode=block" always; + add_header Referrer-Policy "strict-origin-when-cross-origin" always; + + # Logs + access_log /var/log/nginx/karate_photobooth_access.log; + error_log /var/log/nginx/karate_photobooth_error.log; + + # 1. Block access to hidden files and directories (.git, .env, etc.) + location ~ /\. { + deny all; + access_log off; + log_not_found off; + } + + # 2. Block access to sensitive and executable file extensions + location ~* \.(env|git|bak|config|sql|sh|exe|bat|cmd|py|php|cgi)$ { + deny all; + access_log off; + log_not_found off; + } + + # Next.js static asset caching (immutable, high performance) + location /_next/static/ { + proxy_pass http://karate_backend; + proxy_http_version 1.1; + proxy_set_header Connection ""; + expires 365d; + access_log off; + add_header Cache-Control "public, max-age=31536000, immutable"; + } + + # Public static assets + location /assets/ { + proxy_pass http://karate_backend; + proxy_http_version 1.1; + proxy_set_header Connection ""; + expires 30d; + add_header Cache-Control "public, max-age=2592000"; + } + + # Rate-limited auth endpoint + location = /api/portal/auth { + limit_req zone=karate_auth_limit burst=5 nodelay; + limit_req_status 429; + + proxy_pass http://karate_backend; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + + # Rate-limited general API endpoints + location /api/ { + limit_req zone=karate_api_limit burst=25 nodelay; + limit_req_status 429; + + proxy_pass http://karate_backend; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + proxy_connect_timeout 60s; + proxy_send_timeout 120s; + proxy_read_timeout 120s; + proxy_buffering off; + } + + # Main Application Proxy + location / { + proxy_pass http://karate_backend; + proxy_http_version 1.1; + + # WebSocket & connection upgrade headers + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + + # Standard Proxy Headers + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Host $host; + proxy_set_header X-Forwarded-Port $server_port; + + # AI Generation Timeouts + proxy_connect_timeout 60s; + proxy_send_timeout 120s; + proxy_read_timeout 120s; + + # Disable buffering for instant streaming / server-sent events + proxy_buffering off; + } +}