sojorn/FCM_DEPLOYMENT.md

# FCM Notifications - Complete Deployment Guide

## Quick Start (TL;DR)

1. Get VAPID key from Firebase Console
2. Download Firebase service account JSON
3. Update Flutter app with VAPID key
4. Upload JSON to server at `/opt/sojorn/firebase-service-account.json`
5. Add to `/opt/sojorn/.env`: `FIREBASE_CREDENTIALS_FILE=/opt/sojorn/firebase-service-account.json`
6. Restart Go backend
7. Test notifications

---

## Detailed Steps

### 1. Get Firebase Credentials

#### A. Get VAPID Key (for Web Push)

1. Go to https://console.firebase.google.com/project/sojorn-a7a78/settings/cloudmessaging
2. Scroll to **Web configuration** section
3. Under **Web Push certificates**, copy the **Key pair**
4. It should look like: `BNxS7_very_long_string_of_characters...`

#### B. Download Service Account JSON (for Server)

1. Go to https://console.firebase.google.com/project/sojorn-a7a78/settings/serviceaccounts
2. Click **Generate new private key**
3. Click **Generate key** - downloads JSON file
4. Save it somewhere safe (you'll upload it to server)

---

### 2. Update Flutter App with VAPID Key

**File:** `sojorn_app/lib/config/firebase_web_config.dart`

Replace line 24:
```dart
static const String _vapidKey = 'YOUR_VAPID_KEY_HERE';
```

With your actual VAPID key:
```dart
static const String _vapidKey = 'BNxS7_your_actual_vapid_key_from_firebase_console';
```

**Commit and push:**
```bash
cd c:\Webs\Sojorn
git add sojorn_app/lib/config/firebase_web_config.dart
git commit -m "Add FCM VAPID key for web push notifications"
git push
```

---

### 3. Upload Firebase Service Account JSON to Server

**From Windows PowerShell:**
```powershell
scp -i "C:\Users\Patrick\.ssh\mpls.pem" "C:\path\to\sojorn-a7a78-firebase-adminsdk-xxxxx.json" patrick@194.238.28.122:/tmp/firebase-service-account.json
```

Replace `C:\path\to\...` with the actual path to your downloaded JSON file.

---

### 4. Configure Server

**SSH to server:**
```bash
ssh -i "C:\Users\Patrick\.ssh\mpls.pem" patrick@194.238.28.122
```

**Run the setup script:**
```bash
cd /home/patrick
curl -O https://raw.githubusercontent.com/your-repo/sojorn/main/setup_fcm_server.sh
chmod +x setup_fcm_server.sh
./setup_fcm_server.sh
```

**Or manually:**

```bash
# Move JSON file
sudo mv /tmp/firebase-service-account.json /opt/sojorn/firebase-service-account.json
sudo chmod 600 /opt/sojorn/firebase-service-account.json
sudo chown patrick:patrick /opt/sojorn/firebase-service-account.json

# Edit .env
sudo nano /opt/sojorn/.env
```

Add these lines to `.env`:
```bash
# Firebase Cloud Messaging
FIREBASE_CREDENTIALS_FILE=/opt/sojorn/firebase-service-account.json
FIREBASE_WEB_VAPID_KEY=BNxS7_your_actual_vapid_key_here
```

Save and exit (Ctrl+X, Y, Enter)

---

### 5. Restart Go Backend

```bash
cd /home/patrick/sojorn-backend
sudo systemctl restart sojorn-api
sudo systemctl status sojorn-api
```

**Check logs for successful initialization:**
```bash
sudo journalctl -u sojorn-api -f --since "1 minute ago"
```

Look for:
```
[INFO] PushService initialized successfully
```

If you see errors, check:
- JSON file exists: `ls -la /opt/sojorn/firebase-service-account.json`
- .env has correct path: `sudo cat /opt/sojorn/.env | grep FIREBASE`
- JSON is valid: `cat /opt/sojorn/firebase-service-account.json | jq .`

---

### 6. Deploy Flutter App

**Hot restart (no build needed):**
Just refresh your browser or press `R` in the Flutter dev console.

**Or rebuild and deploy:**
```bash
cd c:\Webs\Sojorn\sojorn_app
flutter build web --release
# Deploy to your hosting
```

---

### 7. Test FCM Notifications

#### Test 1: Check Token Registration

1. Open Sojorn web app in browser
2. Open DevTools (F12) > Console
3. Look for: `FCM token registered (web): d2n2ELGKel7yzPL3wZLGSe...`
4. If you see "Web push is missing FIREBASE_WEB_VAPID_KEY", VAPID key is not set correctly

#### Test 2: Check Database

```bash
sudo -u postgres psql sojorn
```

```sql
-- Check FCM tokens are being stored
SELECT user_id, platform, LEFT(fcm_token, 30) as token_preview, created_at 
FROM public.fcm_tokens 
ORDER BY created_at DESC 
LIMIT 5;
```

Expected output:
```
user_id                              | platform | token_preview                  | created_at
-------------------------------------+----------+--------------------------------+-------------------
5568b545-5215-4734-875f-84b3106cd170 | web      | d2n2ELGKel7yzPL3wZLGSe:APA91b | 2026-01-29 05:50
```

#### Test 3: Send Test Message

1. Open two browser windows (or use two different users)
2. User A sends a chat message to User B
3. User B should receive a push notification (if browser is in background)

**Check server logs:**
```bash
sudo journalctl -u sojorn-api -f | grep -i push
```

You should see:
```
[INFO] Sending push notification to user 5568b545...
[INFO] Push notification sent successfully
```

---

## Troubleshooting

### Issue: "Web push is missing FIREBASE_WEB_VAPID_KEY"

**Cause:** VAPID key not set in Flutter app

**Fix:**
1. Update `firebase_web_config.dart` with actual VAPID key
2. Hot restart Flutter app
3. Check console again

### Issue: "Failed to initialize PushService"

**Cause:** Firebase service account JSON not found or invalid

**Fix:**
```bash
# Check file exists
ls -la /opt/sojorn/firebase-service-account.json

# Check .env has correct path
sudo cat /opt/sojorn/.env | grep FIREBASE_CREDENTIALS_FILE

# Validate JSON
cat /opt/sojorn/firebase-service-account.json | jq .

# Check permissions
ls -la /opt/sojorn/firebase-service-account.json
# Should show: -rw------- 1 patrick patrick
```

### Issue: Notifications not received

**Checklist:**
- [ ] Browser notification permissions granted
- [ ] FCM token registered (check console)
- [ ] Token stored in database (check SQL)
- [ ] Go backend logs show push being sent
- [ ] Service worker registered (check DevTools > Application > Service Workers)

**Check service worker:**
1. Open DevTools > Application > Service Workers
2. Should see `firebase-messaging-sw.js` registered
3. If not, check `sojorn_app/web/firebase-messaging-sw.js` exists

---

## Current Configuration

**Firebase Project:**
- Project ID: `sojorn-a7a78`
- Sender ID: `486753572104`
- Console: https://console.firebase.google.com/project/sojorn-a7a78

**Server Paths:**
- .env: `/opt/sojorn/.env`
- Service Account: `/opt/sojorn/firebase-service-account.json`
- Backend: `/home/patrick/sojorn-backend`

**Flutter Files:**
- Config: `sojorn_app/lib/config/firebase_web_config.dart`
- Service Worker: `sojorn_app/web/firebase-messaging-sw.js`
- Notification Service: `sojorn_app/lib/services/notification_service.dart`

---

## How FCM Works in Sojorn

1. **User opens app** → Flutter requests notification permission
2. **Permission granted** → Firebase generates FCM token
3. **Token sent to backend** → Stored in `fcm_tokens` table
4. **Event occurs** (new message, follow, etc.) → Go backend calls `PushService.SendPush()`
5. **FCM sends notification** → User's device/browser receives it
6. **User clicks notification** → App opens to relevant screen

**Notification Triggers:**
- New chat message (`chat_handler.go:156`)
- New follower (`user_handler.go:141`)
- Follow request accepted (`user_handler.go:319`)

---

## Quick Reference Commands

```bash
# SSH to server
ssh -i "C:\Users\Patrick\.ssh\mpls.pem" patrick@194.238.28.122

# Check .env
sudo cat /opt/sojorn/.env | grep FIREBASE

# Check service account file
ls -la /opt/sojorn/firebase-service-account.json
cat /opt/sojorn/firebase-service-account.json | jq .project_id

# Restart backend
sudo systemctl restart sojorn-api

# View logs
sudo journalctl -u sojorn-api -f

# Check FCM tokens in DB
sudo -u postgres psql sojorn -c "SELECT COUNT(*) as token_count FROM public.fcm_tokens;"

# View recent tokens
sudo -u postgres psql sojorn -c "SELECT user_id, platform, created_at FROM public.fcm_tokens ORDER BY created_at DESC LIMIT 5;"
```

---

## Files Modified

1. `sojorn_app/lib/config/firebase_web_config.dart` - Added VAPID key placeholder
2. `go-backend/.env.example` - Updated FCM configuration format
3. Created `FCM_SETUP_GUIDE.md` - Detailed setup instructions
4. Created `setup_fcm_server.sh` - Automated server setup script

---

## Next Steps After Deployment

1. Monitor logs for FCM errors
2. Test notifications with real users
3. Check FCM token count grows as users log in
4. Verify push notifications work on:
   - Chrome (desktop & mobile)
   - Firefox (desktop & mobile)
   - Safari (if supported)
   - Edge

---

## Support

If you encounter issues:
1. Check logs: `sudo journalctl -u sojorn-api -f`
2. Verify configuration: `sudo cat /opt/sojorn/.env | grep FIREBASE`
3. Test JSON validity: `cat /opt/sojorn/firebase-service-account.json | jq .`
4. Check Firebase Console for errors: https://console.firebase.google.com/project/sojorn-a7a78/notification