patrick/sojorn
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
sojorn/sojorn_docs/legacy/FCM_DEPLOYMENT.md

8.6 KiB
Raw Blame History

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:

static const String _vapidKey = 'YOUR_VAPID_KEY_HERE';

With your actual VAPID key:

static const String _vapidKey = 'BNxS7_your_actual_vapid_key_from_firebase_console';

Commit and push:

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:

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:

ssh -i "C:\Users\Patrick\.ssh\mpls.pem" patrick@194.238.28.122

Run the setup script:

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:

# 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:

# 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

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

Check logs for successful initialization:

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:

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

sudo -u postgres psql sojorn

-- 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:

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:

# 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:

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

# 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