@thierrynakoa/fire-flow 12.2.2 → 13.0.1

package/skills-library/database-solutions/supabase-connection-pooler-fix.md

@@ -0,0 +1,102 @@
+# Supabase Connection Pooler - IPv4 Fix
+
+## Problem
+VPS cannot connect to Supabase PostgreSQL database. Two errors occur:
+
+### Error 1: IPv6 Unreachable (Direct Connection)
+```
+Error: connect ENETUNREACH 2600:1f18:2e13:9d18:88be:d4c9:6b70:87e9:5432
+```
+**Cause:** Direct connection (`db.[project].supabase.co:5432`) resolves to IPv6, but VPS has no IPv6 connectivity.
+
+### Error 2: Connection Timeout (Transaction Pooler)
+```
+Error: write CONNECT_TIMEOUT aws-1-us-east-1.pooler.supabase.com:6543
+```
+**Cause:** Transaction pooler on port 6543 may have firewall restrictions or require special configuration.
+
+---
+
+## Solution: Use Session Pooler with URL-Encoded Password
+
+### Working Connection String Format
+```
+postgresql://postgres.[PROJECT_REF]:[URL_ENCODED_PASSWORD]@aws-1-us-east-1.pooler.supabase.com:5432/postgres
+```
+
+### Key Points
+
+1. **Use Session Pooler (port 5432)** - NOT transaction pooler (port 6543)
+   - Session pooler: `pooler.supabase.com:5432`
+   - Transaction pooler: `pooler.supabase.com:6543`
+
+2. **URL Encode Special Characters in Password**
+   - `*` → `%2A`
+   - `@` → `%40`
+   - `/` → `%2F`
+   - `&` → `%26`
+   - `#` → `%23`
+
+   Example: `Jubileess_*7*` → `Jubileess_%2A7%2A`
+
+3. **Username Format for Pooler**
+   - Direct: `postgres`
+   - Pooler: `postgres.[PROJECT_REF]`
+
+---
+
+## Connection String Comparison
+
+### Direct Connection (IPv6 issues)
+```
+postgresql://postgres:PASSWORD@db.[PROJECT].supabase.co:5432/postgres
+```
+
+### Transaction Pooler (may timeout)
+```
+postgresql://postgres.[PROJECT]:PASSWORD@aws-1-us-east-1.pooler.supabase.com:6543/postgres?pgbouncer=true
+```
+
+### Session Pooler (RECOMMENDED for VPS)
+```
+postgresql://postgres.[PROJECT]:URL_ENCODED_PASSWORD@aws-1-us-east-1.pooler.supabase.com:5432/postgres
+```
+
+---
+
+## How to Find Your Pooler URL
+
+1. Go to Supabase Dashboard
+2. Click "Connect" button
+3. Select "Connection String" tab
+4. Change "Method" dropdown to "Session pooler"
+5. Note: It says "IPv4 compatible" at the bottom
+
+---
+
+## Verification
+
+After updating `.env`, restart the server and check logs:
+```bash
+pm2 restart all
+pm2 logs lms-server --lines 20
+```
+
+**Success indicator:**
+```
+✅ [DATABASE] Connection successful! Supabase PostgreSQL is ready.
+```
+
+**Failure indicators:**
+```
+❌ [DATABASE] Failed to connect to Supabase PostgreSQL
+Error: connect ENETUNREACH ...  # IPv6 issue
+Error: write CONNECT_TIMEOUT ... # Pooler/firewall issue
+```
+
+---
+
+## References
+- [Supabase Connection Management](https://supabase.com/docs/guides/database/connection-management)
+- [Supabase GitHub Discussion #21789](https://github.com/orgs/supabase/discussions/21789)
+- [Supavisor FAQ](https://supabase.com/docs/guides/troubleshooting/supavisor-faq-YyP5tI)

package/skills-library/deployment-security/CPANEL_NODE_DEPLOYMENT.md

@@ -0,0 +1,166 @@
+# cPanel Node.js Application Deployment via PHP Installer
+
+## Overview
+Deploy Node.js applications on shared cPanel hosting using a WordPress-style PHP installer wizard. This approach enables non-technical users to deploy complex Node.js/React applications without command line access.
+
+## Architecture
+
+### Two-Phase Deployment
+1. **PHP Installer (Web-Based)** - Collects configuration, tests connections, generates .env
+2. **Node.js Server** - Runs via cPanel's Node.js Selector or PM2
+
+### Directory Structure on cPanel
+```
+public_html/
+├── install/                 # PHP installer wizard (delete after install)
+│   ├── index.php           # Main entry with AJAX handlers
+│   ├── includes/
+│   │   ├── requirements.php
+│   │   └── functions.php
+│   └── steps/
+│       └── step1-13.php
+├── server/                  # Node.js backend
+│   ├── server.js
+│   ├── package.json
+│   ├── .env                # Generated by installer
+│   └── database/
+│       └── adapters/       # MySQL/PostgreSQL support
+└── client/                  # React frontend (built)
+    └── dist/
+```
+
+## SSH Deployment Commands
+
+### Initial Upload
+```bash
+# Upload installer
+scp -i "path/to/ssh-key" -r install/ user@host:/home/user/public_html/
+
+# Upload server files
+scp -i "path/to/ssh-key" -r server/ user@host:/home/user/public_html/
+
+# Upload built client
+scp -i "path/to/ssh-key" -r client/dist/ user@host:/home/user/public_html/client/
+```
+
+### Database Setup via cPanel uapi
+```bash
+# Create database
+uapi Mysql create_database name="user_dbname"
+
+# Create user
+uapi Mysql create_user name="user_dbuser" password="SecurePass123!"
+
+# Grant privileges
+uapi Mysql set_privileges_on_database user="user_dbuser" database="user_dbname" privileges="ALL PRIVILEGES"
+```
+
+### Node.js Setup
+```bash
+# Install dependencies
+cd ~/public_html/server && npm install
+
+# Start with PM2
+pm2 start server.js --name "lms-server"
+pm2 save
+```
+
+## PHP Installer Features
+
+### 13-Step Wizard
+1. Welcome
+2. Requirements Check (PHP, Node.js, extensions)
+3. License Key Validation
+4. Database Configuration (MySQL/PostgreSQL toggle)
+5. Site Configuration (name, URL, timezone)
+6. Admin Account Creation
+7. Theme Selection
+8. Organization Details
+9. Branding (logo, colors)
+10. Email Configuration (SMTP/SendGrid)
+11. Summary Review
+12. Installation Progress
+13. Completion
+
+### Key PHP Functions
+```php
+// Test database connection
+function testDatabaseConnection($config) {
+    $dbType = $config['db_type'] ?? 'mysql';
+    $dsn = $dbType === 'mysql'
+        ? "mysql:host={$host};port={$port};dbname={$name};charset=utf8mb4"
+        : "pgsql:host={$host};port={$port};dbname={$name}";
+
+    $pdo = new PDO($dsn, $user, $pass, [
+        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
+        PDO::ATTR_TIMEOUT => 5
+    ]);
+    return ['success' => true];
+}
+
+// Generate .env file
+function generateEnvFile($config) {
+    $content = "DB_TYPE=" . $config['db_type'] . "\n";
+    $content .= "DB_HOST=" . $config['db_host'] . "\n";
+    // ... more variables
+    $content .= "JWT_SECRET=" . bin2hex(random_bytes(32)) . "\n";
+    return file_put_contents('../server/.env', $content);
+}
+```
+
+## Database Abstraction Layer
+
+### Knex.js Cross-Database Support
+```javascript
+// server/database/config.js
+const dbType = process.env.DB_TYPE || 'pg';
+const isSupabase = process.env.DATABASE_URL?.includes('supabase');
+
+const config = {
+  client: dbType === 'mysql' ? 'mysql2' : 'pg',
+  connection: {
+    host: process.env.DB_HOST,
+    port: process.env.DB_PORT,
+    database: process.env.DB_NAME,
+    user: process.env.DB_USER,
+    password: process.env.DB_PASS,
+    ssl: isSupabase ? { rejectUnauthorized: false } : false
+  }
+};
+```
+
+### Adapter Pattern
+```javascript
+// PostgreSQL: JSONB, ILIKE, upsert with ON CONFLICT
+// MySQL: JSON columns, CONCAT_WS, REPLACE INTO
+class PostgresAdapter extends BaseAdapter {
+  async search(table, column, query) {
+    return this.db(table).where(column, 'ilike', `%${query}%`);
+  }
+}
+
+class MySQLAdapter extends BaseAdapter {
+  async search(table, column, query) {
+    return this.db(table).where(column, 'like', `%${query}%`);
+  }
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+1. **Node.js not found** - Use cPanel Node.js Selector to register app
+2. **Database connection refused** - Check if localhost or 127.0.0.1 is required
+3. **Permission denied** - Ensure 755 for directories, 644 for files
+4. **SSL errors with Supabase** - Add `ssl: { rejectUnauthorized: false }`
+
+### DNS Configuration
+- Remove any conflicting nameservers (e.g., Vercel)
+- Point A record to cPanel server IP
+- Allow 24-48 hours for propagation
+
+## Security Reminders
+1. Delete `/install` folder after successful installation
+2. Set restrictive permissions on `.env` file (600)
+3. Use HTTPS in production
+4. Enable cPanel firewall rules

package/skills-library/deployment-security/DEPLOYMENT.md

@@ -0,0 +1,275 @@
+# 🚢 Deployment Guide
+
+This guide covers deploying the Melchizedek Priests Ministry MERN stack application to production.
+
+## 📋 Prerequisites
+
+- Node.js 18+ installed
+- MongoDB database (MongoDB Atlas recommended)
+- Domain name (optional but recommended)
+- Git repository
+
+## 🚀 Quick Deployment Options
+
+### Option 1: Vercel + Railway (Recommended)
+
+#### Frontend Deployment (Vercel)
+1. **Connect to Vercel**
+   ```bash
+   # Install Vercel CLI
+   npm i -g vercel
+
+   # Login to Vercel
+   vercel login
+
+   # Deploy frontend
+   cd client
+   vercel --prod
+   ```
+
+2. **Configure Environment Variables**
+   In Vercel dashboard, add:
+   ```
+   VITE_API_URL=https://your-backend-url.vercel.app/api
+   VITE_STRIPE_PUBLISHABLE_KEY=pk_live_...
+   ```
+
+#### Backend Deployment (Railway)
+1. **Connect to Railway**
+   - Go to [Railway.app](https://railway.app)
+   - Connect your GitHub repository
+   - Railway will auto-detect and deploy
+
+2. **Environment Variables**
+   Set these in Railway:
+   ```
+   NODE_ENV=production
+   PORT=5000
+   MONGO_URI=mongodb+srv://...
+   JWT_SECRET=your-secret-key
+   STRIPE_SECRET_KEY=sk_live_...
+   EMAIL_USER=your-email@gmail.com
+   EMAIL_PASS=your-app-password
+   ```
+
+### Option 2: Netlify + Render
+
+#### Frontend Deployment (Netlify)
+1. **Connect Repository**
+   - Go to [Netlify.com](https://netlify.com)
+   - Connect GitHub repository
+   - Set build command: `npm run build`
+   - Set publish directory: `client/dist`
+
+2. **Environment Variables**
+   ```
+   VITE_API_URL=https://your-backend.onrender.com/api
+   VITE_STRIPE_PUBLISHABLE_KEY=pk_live_...
+   ```
+
+#### Backend Deployment (Render)
+1. **Create Web Service**
+   - Go to [Render.com](https://render.com)
+   - Create new Web Service
+   - Connect GitHub repository
+   - Set build command: `npm install`
+   - Set start command: `npm start`
+
+2. **Environment Variables**
+   Same as Railway configuration above.
+
+## 🔧 Manual Deployment
+
+### 1. Environment Setup
+
+Create `.env` files in both `client/` and `server/` directories:
+
+**server/.env**
+```env
+NODE_ENV=production
+PORT=5000
+MONGO_URI=mongodb+srv://username:password@cluster.mongodb.net/dbname
+JWT_SECRET=your-super-secret-jwt-key
+JWT_EXPIRE=30d
+STRIPE_SECRET_KEY=sk_live_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+EMAIL_USER=your-email@gmail.com
+EMAIL_PASS=your-app-password
+EMAIL_FROM=noreply@melchizedekpriests.com
+```
+
+**client/.env**
+```env
+VITE_API_URL=https://your-domain.com/api
+VITE_STRIPE_PUBLISHABLE_KEY=pk_live_...
+VITE_APP_NAME=Melchizedek Priests Ministry
+```
+
+### 2. Build Application
+
+```bash
+# Install all dependencies
+npm run install-all
+
+# Build frontend
+npm run build
+
+# Start production servers
+npm start
+```
+
+### 3. Server Configuration
+
+For production servers, configure:
+
+**Nginx Configuration** (`/etc/nginx/sites-available/melchizedekpriests.com`)
+```nginx
+server {
+    listen 80;
+    server_name melchizedekpriests.com www.melchizedekpriests.com;
+
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        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_cache_bypass $http_upgrade;
+    }
+
+    location /api {
+        proxy_pass http://localhost:5000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        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_cache_bypass $http_upgrade;
+    }
+}
+```
+
+**PM2 Configuration** (`ecosystem.config.js`)
+```javascript
+module.exports = {
+  apps: [
+    {
+      name: 'melchizedek-client',
+      script: 'npm start',
+      cwd: '/path/to/client',
+      env: {
+        NODE_ENV: 'production',
+        PORT: 3000
+      }
+    },
+    {
+      name: 'melchizedek-server',
+      script: 'npm start',
+      cwd: '/path/to/server',
+      env: {
+        NODE_ENV: 'production',
+        PORT: 5000
+      }
+    }
+  ]
+};
+```
+
+## 🔒 Security Checklist
+
+- [ ] HTTPS enabled (Let's Encrypt recommended)
+- [ ] Environment variables properly set
+- [ ] Database secured with IP whitelisting
+- [ ] JWT secrets are strong and unique
+- [ ] CORS configured for production domain
+- [ ] Rate limiting implemented
+- [ ] Security headers set (helmet.js)
+- [ ] Regular security updates scheduled
+
+## 📊 Monitoring & Maintenance
+
+### Health Checks
+- Frontend: `https://yourdomain.com/health`
+- Backend: `https://yourdomain.com/api/health`
+
+### Logs
+```bash
+# PM2 logs
+pm2 logs
+
+# Nginx logs
+sudo tail -f /var/log/nginx/access.log
+sudo tail -f /var/log/nginx/error.log
+```
+
+### Database Backups
+```bash
+# MongoDB Atlas automatic backups recommended
+# Or manual backup script
+mongodump --db yourdb --out /path/to/backup/$(date +%Y%m%d)
+```
+
+## 🚨 Troubleshooting
+
+### Common Issues
+
+**Build Fails**
+```bash
+# Clear cache and rebuild
+rm -rf node_modules client/node_modules server/node_modules
+npm run install-all
+npm run build
+```
+
+**Database Connection Issues**
+- Check MongoDB Atlas IP whitelist
+- Verify connection string format
+- Test connection with MongoDB Compass
+
+**Environment Variables**
+```bash
+# Check if variables are loaded
+node -e "console.log(process.env)"
+```
+
+**CORS Issues**
+- Update CORS origins in server config
+- Check for http vs https mismatches
+
+## 📞 Support
+
+For deployment issues:
+- Check application logs
+- Verify environment variables
+- Test API endpoints with Postman
+- Contact [support@melchizedekpriests.com](mailto:support@melchizedekpriests.com)
+
+## 🔄 Updates & Rollbacks
+
+### Zero-Downtime Updates
+```bash
+# Update code
+git pull origin main
+
+# Install dependencies
+npm run install-all
+
+# Build and restart
+npm run build
+pm2 restart all
+```
+
+### Rollback
+```bash
+# Rollback to previous commit
+git log --oneline -10
+git checkout <commit-hash>
+npm run install-all
+npm run build
+pm2 restart all
+```