documentation

docs/DEPLOY_FROM_SCRATCH.md

@@ -1,5 +1,7 @@
 # Deploying PunimTag (From Scratch, Simple)
 
+> **Deploying via CPanel?** See [`DEPLOY_CPANEL.md`](./DEPLOY_CPANEL.md) for CPanel-specific instructions.
+
 This guide is for a **fresh install** where the databases do **not** need to be migrated.
 You will start with **empty PostgreSQL databases** and deploy the app from a copy of the repo
 (e.g., downloaded from **SharePoint**).

docs/FIX_ADMIN_LOGIN_WORDPRESS_REDIRECT.md

@@ -0,0 +1,140 @@
+# Fix Admin Login WordPress Redirect
+
+## Problem
+Login redirects to WordPress (`wp-login.php`) instead of calling FastAPI.
+
+## Root Cause
+The admin frontend is calling `/api/v1/auth/login` (relative path) which WordPress intercepts. It should call `/punim-api/api/v1/auth/login`.
+
+This happens because **Vite environment variables are injected at BUILD TIME**, not runtime. If you changed `.env` but didn't rebuild, the old code is still running.
+
+## Solution
+
+### Step 1: Verify Environment Variable
+
+```bash
+cd ~/punimtag/admin-frontend
+cat .env | grep VITE_API_URL
+```
+
+Should show:
+```
+VITE_API_URL=/punim-api
+```
+
+If missing or wrong:
+```bash
+nano admin-frontend/.env
+# Add: VITE_API_URL=/punim-api
+# Save: Ctrl+X, Y, Enter
+```
+
+### Step 2: REBUILD Admin Frontend (CRITICAL!)
+
+**This is required!** Vite reads `.env` during build:
+
+```bash
+cd ~/punimtag/admin-frontend
+npm run build
+```
+
+Wait for completion. You should see:
+```
+✓ built in X.XXs
+```
+
+### Step 3: Verify Build Contains Correct URL
+
+```bash
+cd ~/punimtag/admin-frontend
+grep -r "punim-api" dist/ | head -3
+```
+
+Should show `/punim-api` in JavaScript files.
+
+### Step 4: Restart Admin Service
+
+```bash
+pm2 restart punimtag-admin
+```
+
+### Step 5: Clear Browser Cache
+
+- **Hard refresh:** `Ctrl+Shift+R` (Windows/Linux) or `Cmd+Shift+R` (Mac)
+- Or open DevTools → Network tab → check "Disable cache"
+
+### Step 6: Verify Request URL
+
+1. Open admin frontend: `https://jrccphotos.org/punim-admin/`
+2. Open DevTools → Network tab
+3. Try to login
+4. Check the POST request URL:
+   - ✅ **Correct:** `https://jrccphotos.org/punim-api/api/v1/auth/login`
+   - ❌ **Wrong:** `https://jrccphotos.org/api/v1/auth/login` (means rebuild didn't work)
+
+## Why This Happens
+
+Vite environment variables work like this:
+
+1. **Build time:** Vite reads `VITE_API_URL` from `.env` and replaces `import.meta.env.VITE_API_URL` in code
+2. **Runtime:** The built JavaScript has the actual value hardcoded
+
+If you change `.env` but don't rebuild:
+- Old build still has old value
+- New `.env` value is ignored
+- WordPress intercepts relative paths
+
+## Troubleshooting
+
+### Still redirects to WordPress after rebuild?
+
+1. **Check if dist/ folder was updated:**
+   ```bash
+   ls -lt ~/punimtag/admin-frontend/dist/ | head -5
+   ```
+   Should show recent timestamps.
+
+2. **Check PM2 is serving from dist/:**
+   ```bash
+   pm2 logs punimtag-admin --lines 20
+   ```
+   Should show it's serving from `dist/` directory.
+
+3. **Check serve.sh script:**
+   ```bash
+   cat ~/punimtag/admin-frontend/serve.sh
+   ```
+   Should serve from `dist/` directory.
+
+4. **Verify VITE_API_URL in built code:**
+   ```bash
+   cd ~/punimtag/admin-frontend
+   grep -o "punim-api" dist/assets/*.js | head -1
+   ```
+   Should find `/punim-api` in the built files.
+
+### Build fails?
+
+- Check Node.js version: `node --version` (need 18+)
+- Check npm install: `cd admin-frontend && npm install`
+- Check for errors: `npm run build 2>&1 | tail -20`
+
+## Quick Checklist
+
+- [ ] `VITE_API_URL=/punim-api` in `admin-frontend/.env`
+- [ ] Ran `npm run build` in `admin-frontend/` directory
+- [ ] Build completed successfully (no errors)
+- [ ] Verified `/punim-api` appears in `dist/` files
+- [ ] Restarted PM2: `pm2 restart punimtag-admin`
+- [ ] Cleared browser cache (hard refresh)
+- [ ] Checked browser Network tab - request goes to `/punim-api/api/v1/auth/login`
+
+---
+
+**Remember:** Every time you change `VITE_API_URL` in `.env`, you MUST rebuild!
+
+
+
+
+
+

docs/FIX_LOGIN_REDIRECT_BUG.md

@@ -0,0 +1,124 @@
+# Fix Login Redirect Bug - Client Server
+
+## Problem
+When login fails (401 error), the code redirects to `/login` which WordPress intercepts. It should redirect to `/punim-admin/login`.
+
+## Root Cause
+In `admin-frontend/src/api/client.ts`, the error handler uses:
+```typescript
+window.location.href = '/login'  // ❌ Wrong - goes to domain root
+```
+
+This should be:
+```typescript
+window.location.href = '/punim-admin/login'  // ✅ Correct
+```
+
+## Fix on Client Server
+
+### Option 1: Quick Fix (Edit Built File - Temporary)
+
+**⚠️ Warning:** This will be overwritten on next rebuild!
+
+```bash
+cd ~/punimtag/admin-frontend/dist/assets
+
+# Find the JavaScript file
+JS_FILE=$(ls index-*.js | head -1)
+
+# Backup
+cp "$JS_FILE" "$JS_FILE.backup"
+
+# Replace /login with /punim-admin/login (only in redirect contexts)
+sed -i 's|window.location.href="/login"|window.location.href="/punim-admin/login"|g' "$JS_FILE"
+sed -i "s|window.location.href='/login'|window.location.href='/punim-admin/login'|g" "$JS_FILE"
+
+# Restart
+pm2 restart punimtag-admin
+```
+
+### Option 2: Fix Source Code (Permanent)
+
+Edit the source file on client server:
+
+```bash
+cd ~/punimtag/admin-frontend/src/api
+nano client.ts
+```
+
+Find these lines (around lines 44 and 65):
+```typescript
+window.location.href = '/login'
+```
+
+Replace with:
+```typescript
+window.location.href = '/punim-admin/login'
+```
+
+Then rebuild:
+```bash
+cd ~/punimtag/admin-frontend
+npm run build
+pm2 restart punimtag-admin
+```
+
+## Verification
+
+After fix:
+1. Try to login with wrong credentials
+2. Should stay on admin frontend (show error message)
+3. Should NOT redirect to WordPress
+4. Check browser URL - should be `https://jrccphotos.org/punim-admin/login`
+
+## What to Change
+
+In `admin-frontend/src/api/client.ts`, change:
+
+**Line ~44:**
+```typescript
+// OLD:
+window.location.href = '/login'
+
+// NEW:
+window.location.href = '/punim-admin/login'
+```
+
+**Line ~65:**
+```typescript
+// OLD:
+window.location.href = '/login'
+
+// NEW:
+window.location.href = '/punim-admin/login'
+```
+
+**Line ~42 (check):**
+```typescript
+// OLD:
+const isLoginPage = window.location.pathname === '/login'
+
+// NEW:
+const isLoginPage = window.location.pathname === '/punim-admin/login' || window.location.pathname === '/punim-admin/'
+```
+
+## Better Solution (Future)
+
+Use a helper function to get the base path dynamically:
+```typescript
+const getBasePath = () => {
+  const path = window.location.pathname;
+  if (path.startsWith('/punim-admin')) return '/punim-admin';
+  return '';
+};
+
+window.location.href = `${getBasePath()}/login`;
+```
+
+But for now, the hardcoded `/punim-admin/login` fix will work.
+
+
+
+
+
+