sojorn/FCM_SETUP_GUIDE.md

# Firebase Cloud Messaging (FCM) Setup Guide

## Overview

This guide will help you configure FCM push notifications for the Sojorn app. You need:
1. **VAPID Key** - For web push notifications
2. **Firebase Service Account JSON** - For server-side FCM API access

---

## Step 1: Get Your VAPID Key from Firebase Console

1. Go to [Firebase Console](https://console.firebase.google.com/)
2. Select your project: **sojorn-a7a78**
3. Click the gear icon ⚙️ > **Project Settings**
4. Go to the **Cloud Messaging** tab
5. Scroll down to **Web configuration**
6. Under **Web Push certificates**, you'll see your VAPID key pair
7. If you don't have one, click **Generate key pair**
8. Copy the **Key pair** (starts with `B...`)

**Example VAPID Key format:**
```
BNxS7_example_vapid_key_here_very_long_string_of_characters
```

---

## Step 2: Get Your Firebase Service Account JSON

1. Still in Firebase Console > **Project Settings**
2. Go to the **Service Accounts** tab
3. Click **Generate new private key**
4. Click **Generate key** - this downloads a JSON file
5. The file will be named something like: `sojorn-a7a78-firebase-adminsdk-xxxxx-xxxxxxxxxx.json`

**Example JSON structure:**
```json
{
  "type": "service_account",
  "project_id": "sojorn-a7a78",
  "private_key_id": "abc123...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "firebase-adminsdk-xxxxx@sojorn-a7a78.iam.gserviceaccount.com",
  "client_id": "123456789...",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/..."
}
```

---

## Step 3: Update Server Configuration (/opt/sojorn/.env)

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

Edit the .env file:
```bash
sudo nano /opt/sojorn/.env
```

Add these lines (replace with your actual values):
```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)

---

## Step 4: Upload Firebase Service Account JSON to Server

From your local machine, upload the JSON file:
```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
```

Then on the server, move it to the correct location:
```bash
ssh -i "C:\Users\Patrick\.ssh\mpls.pem" patrick@194.238.28.122
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
```

Verify the file exists:
```bash
ls -la /opt/sojorn/firebase-service-account.json
```

---

## Step 5: Update Flutter App with VAPID Key

The VAPID key needs to be hardcoded in the Flutter app (already done in the code changes below).

---

## Step 6: Restart Go Backend

```bash
ssh -i "C:\Users\Patrick\.ssh\mpls.pem" patrick@194.238.28.122
cd /home/patrick/sojorn-backend
sudo systemctl restart sojorn-api
sudo systemctl status sojorn-api
```

Check logs for FCM initialization:
```bash
sudo journalctl -u sojorn-api -f --since "5 minutes ago"
```

You should see:
```
[INFO] PushService initialized successfully
```

If you see:
```
[WARN] Failed to initialize PushService
```

Check that:
- The JSON file exists at `/opt/sojorn/firebase-service-account.json`
- The file has correct permissions (600)
- The JSON is valid (not corrupted)

---

## Step 7: Test FCM Notifications

### Test 1: Register FCM Token

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

### Test 2: Send a Test Notification

From your server, you can test sending a notification:

```bash
# Get a user's FCM token from database
sudo -u postgres psql sojorn -c "SELECT fcm_token FROM public.fcm_tokens LIMIT 1;"

# The Go backend will automatically send push notifications when:
# - Someone sends you a chat message
# - Someone follows you
# - Someone accepts your follow request
```

### Test 3: Verify in Database

Check that FCM tokens are being stored:
```bash
sudo -u postgres psql sojorn
SELECT user_id, platform, LEFT(fcm_token, 20) as token_preview, created_at 
FROM public.fcm_tokens 
ORDER BY created_at DESC 
LIMIT 5;
```

---

## Troubleshooting

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

**Solution:** The VAPID key is not configured in the Flutter app. Make sure the code changes below are deployed.

### Issue: "Failed to initialize PushService"

**Possible causes:**
1. Firebase service account JSON file not found
2. Invalid JSON file
3. Wrong file path in .env

**Check:**
```bash
cat /opt/sojorn/.env | grep FIREBASE
ls -la /opt/sojorn/firebase-service-account.json
cat /opt/sojorn/firebase-service-account.json | jq .
```

### Issue: Notifications not received

**Check:**
1. Browser notification permissions granted
2. FCM token registered (check console logs)
3. Go backend logs show push being sent
4. Database has FCM token for user

---

## Current Configuration

**Firebase Project:** sojorn-a7a78
**Project ID:** sojorn-a7a78
**Sender ID:** 486753572104

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

---

## Quick Reference Commands

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

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

# Check service account file
ls -la /opt/sojorn/firebase-service-account.json

# 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(*) FROM public.fcm_tokens;"
```