docs/DEPLOY_FROM_SCRATCH.md

@@ -56,6 +56,59 @@ sudo ufw allow 3001/tcp  # Viewer frontend
 sudo ufw allow 8000/tcp  # Backend API
 ```
 
+### PostgreSQL Remote Connection Setup (if using remote database)
+
+If your PostgreSQL database is on a **separate server** from the application, you need to configure PostgreSQL to accept remote connections.
+
+**On the PostgreSQL database server:**
+
+1. **Edit `pg_hba.conf`** to allow connections from your application server:
+   ```bash
+   sudo nano /etc/postgresql/*/main/pg_hba.conf
+   ```
+   
+   Add a line allowing connections from your application server IP:
+   ```bash
+   # Allow connections from application server
+   host    all             all             10.0.10.121/32         md5
+   ```
+   
+   Replace `10.0.10.121` with your actual application server IP address.
+   Replace `md5` with `scram-sha-256` if your PostgreSQL version uses that (PostgreSQL 14+).
+
+2. **Edit `postgresql.conf`** to listen on network interfaces:
+   ```bash
+   sudo nano /etc/postgresql/*/main/postgresql.conf
+   ```
+   
+   Find and update the `listen_addresses` setting:
+   ```bash
+   listen_addresses = '*'  # Listen on all interfaces
+   # OR for specific IP:
+   # listen_addresses = 'localhost,10.0.10.181'  # Replace with your DB server IP
+   ```
+
+3. **Restart PostgreSQL** to apply changes:
+   ```bash
+   sudo systemctl restart postgresql
+   ```
+
+4. **Configure firewall** on the database server to allow PostgreSQL connections:
+   ```bash
+   sudo ufw allow from 10.0.10.121 to any port 5432  # Replace with your app server IP
+   # OR allow from all (less secure):
+   # sudo ufw allow 5432/tcp
+   ```
+
+5. **Test the connection** from the application server:
+   ```bash
+   psql -h 10.0.10.181 -U punim_dev_user -d postgres
+   ```
+   
+   Replace `10.0.10.181` with your database server IP and `punim_dev_user` with your database username.
+
+**Note:** If PostgreSQL is on the same server as the application, you can skip this step and use `localhost` in your connection strings.
+
 ---
 
 ## Fast path (recommended): run the deploy script
@@ -71,6 +124,7 @@ chmod +x scripts/deploy_from_scratch.sh
 The script will:
 - Install system packages (including Redis)
 - Configure firewall rules (optional, with prompt)
+- Prompt for PostgreSQL remote connection setup (if using remote database)
 - Copy `*_example` env files to real `.env` files (if missing)
 - Install Python + Node dependencies
 - Generate Prisma clients for the viewer
@@ -128,6 +182,8 @@ PHOTO_STORAGE_DIR=/opt/punimtag/data/uploads
 REDIS_URL=redis://127.0.0.1:6379/0
 ```
 
+**Important:** If using a **remote PostgreSQL server**, ensure you've completed the "PostgreSQL Remote Connection Setup" steps in the Prerequisites section above before configuring these connection strings.
+
 Notes:
 - The backend **auto-creates tables** on first run if they are missing.
 - The backend will also attempt to create the databases **if** the configured Postgres user has

scripts/deploy_from_scratch.sh

@@ -64,7 +64,58 @@ else
 fi
 
 echo ""
-echo "== 3) Ensure env files exist (copied from *_example) =="
+echo "== 3) Configure firewall rules (optional) =="
+if command_exists ufw; then
+  echo "Configure UFW firewall rules for application ports?"
+  echo "  - Port 3000 (Admin frontend)"
+  echo "  - Port 3001 (Viewer frontend)"
+  echo "  - Port 8000 (Backend API)"
+  echo ""
+  read -p "Add firewall rules? [y/N] " -n 1 -r
+  echo ""
+  if [[ $REPLY =~ ^[Yy]$ ]]; then
+    sudo ufw allow 3000/tcp
+    sudo ufw allow 3001/tcp
+    sudo ufw allow 8000/tcp
+    echo "✅ Firewall rules added"
+  else
+    echo "⏭️  Skipped firewall rules (configure manually if needed)"
+  fi
+else
+  echo "⏭️  UFW not found, skipping firewall configuration"
+fi
+
+echo ""
+echo "== 3.5) PostgreSQL Remote Connection Setup (if using remote database) =="
+echo "If your PostgreSQL database is on a separate server, you need to configure"
+echo "PostgreSQL to accept remote connections."
+echo ""
+echo "⚠️  IMPORTANT: This configuration must be done ON THE DATABASE SERVER."
+echo "   Configure PostgreSQL before starting services (Step 11)."
+echo ""
+echo "Required steps on the DATABASE SERVER:"
+echo ""
+echo "1. Edit pg_hba.conf:"
+echo "   sudo nano /etc/postgresql/*/main/pg_hba.conf"
+echo "   Add line: host all all YOUR_APP_SERVER_IP/32 md5"
+echo ""
+echo "2. Edit postgresql.conf:"
+echo "   sudo nano /etc/postgresql/*/main/postgresql.conf"
+echo "   Set: listen_addresses = '*'"
+echo ""
+echo "3. Restart PostgreSQL:"
+echo "   sudo systemctl restart postgresql"
+echo ""
+echo "4. Configure firewall on DB server:"
+echo "   sudo ufw allow from YOUR_APP_SERVER_IP to any port 5432"
+echo ""
+echo "5. Test connection from this server:"
+echo "   psql -h YOUR_DB_SERVER_IP -U YOUR_DB_USER -d postgres"
+echo ""
+echo "⏭️  Continuing with deployment. Ensure PostgreSQL is configured before Step 11."
+
+echo ""
+echo "== 4) Ensure env files exist (copied from *_example) =="
 ensure_file_from_example "${PROJECT_ROOT}/.env_example" "${PROJECT_ROOT}/.env"
 ensure_file_from_example "${PROJECT_ROOT}/admin-frontend/.env_example" \
   "${PROJECT_ROOT}/admin-frontend/.env"
@@ -81,7 +132,7 @@ echo "Press Enter once they are updated..."
 read -r
 
 echo ""
-echo "== 4) Backend Python venv + deps =="
+echo "== 5) Backend Python venv + deps =="
 cd "${PROJECT_ROOT}"
 python3 -m venv venv
 ./venv/bin/pip install --upgrade pip
@@ -89,35 +140,62 @@ python3 -m venv venv
 echo "✅ Backend dependencies installed"
 
 echo ""
-echo "== 5) Admin frontend deps =="
+echo "== 6) Admin frontend deps =="
 cd "${PROJECT_ROOT}/admin-frontend"
 npm ci
 echo "✅ Admin dependencies installed"
 
 echo ""
-echo "== 6) Viewer frontend deps + Prisma clients =="
+echo "== 7) Viewer frontend deps + Prisma clients =="
 cd "${PROJECT_ROOT}/viewer-frontend"
 npm ci
 npm run prisma:generate:all
 echo "✅ Viewer dependencies installed and Prisma clients generated"
 
 echo ""
-echo "== 7) Auth DB setup scripts (viewer) =="
+echo "== 8) Auth DB setup scripts (viewer) =="
 cd "${PROJECT_ROOT}/viewer-frontend"
 npx tsx scripts/setup-auth.ts
 npx tsx scripts/fix-admin-user.ts
 echo "✅ Auth DB setup done"
 
 echo ""
-echo "== 8) Start services (PM2) =="
+echo "== 9) Build frontends =="
+echo "Building admin frontend..."
+cd "${PROJECT_ROOT}/admin-frontend"
+npm run build
+echo "✅ Admin frontend built"
+
+echo ""
+echo "Building viewer frontend..."
+cd "${PROJECT_ROOT}/viewer-frontend"
+npm run build
+echo "✅ Viewer frontend built"
+
+echo ""
+echo "== 10) Configure PM2 =="
 if ! command_exists pm2; then
   echo "Installing PM2..."
   sudo npm i -g pm2
 fi
 
+cd "${PROJECT_ROOT}"
+ensure_file_from_example \
+  "${PROJECT_ROOT}/ecosystem.config.js.example" \
+  "${PROJECT_ROOT}/ecosystem.config.js"
+
+echo ""
+echo "⚠️  IMPORTANT: Review and edit ${PROJECT_ROOT}/ecosystem.config.js"
+echo "   Update paths (cwd, error_file, out_file, PYTHONPATH, PATH) for your server."
+echo ""
+read -p "Press Enter once ecosystem.config.js is configured (or to use defaults)..."
+
+echo ""
+echo "== 11) Start services (PM2) =="
 cd "${PROJECT_ROOT}"
 pm2 start ecosystem.config.js
 pm2 save
+echo "✅ Services started with PM2"
 
 echo ""
 echo "✅ Done."