rosterchirp/fcm-app/README.md

# FCM Test PWA

A Progressive Web App for testing Firebase Cloud Messaging (FCM) notifications across desktop and mobile devices.

## Features

- PWA with install capability
- Firebase Cloud Messaging integration
- Multi-user support (pwau1, pwau2, pwau3)
- SSL/HTTPS ready
- Docker deployment
- Real-time notifications

## Quick Start

### 1. Firebase Setup

1. **Create Firebase Project**
   - Go to [Firebase Console](https://console.firebase.google.com/)
   - Click "Add project"
   - Enter project name (e.g., "fcm-test-pwa")
   - Enable Google Analytics (optional)
   - Click "Create project"

2. **Enable Cloud Messaging**
   - In your project dashboard, go to "Build" → "Cloud Messaging"
   - Click "Get started"
   - Cloud Messaging is now enabled for your project

3. **Get Firebase Configuration**
   - Go to Project Settings (⚙️ icon)
   - Under "Your apps", click "Web app" (</> icon)
   - Register app with nickname "FCM Test PWA"
   - Copy the Firebase config object (you'll need this later)

4. **Generate Service Account Key**
   - In Project Settings, go to "Service accounts"
   - Click "Generate new private key"
   - Save the JSON file (you'll need this for the server)

5. **Get Web Push Certificate**
   - In Cloud Messaging settings, click "Web Push certificates"
   - Generate and save the key pair

### 2. Server Configuration

1. **Copy environment template**
   ```bash
   cp .env.example .env
   ```

2. **Update .env file** with your Firebase credentials:
   ```env
   FIREBASE_PROJECT_ID=your-project-id
   FIREBASE_PRIVATE_KEY_ID=your-private-key-id
   FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
   FIREBASE_CLIENT_EMAIL=firebase-adminsdk-...@your-project-id.iam.gserviceaccount.com
   FIREBASE_CLIENT_ID=your-client-id
   # ... other fields from service account JSON
   ```

3. **Update Firebase config in client files**:
   - Edit `public/app.js` - replace Firebase config
   - Edit `public/sw.js` - replace Firebase config

### 3. Local Development

```bash
# Install dependencies
npm install

# Start development server
npm run dev
```

Open http://localhost:3000 in your browser.

### 4. Docker Deployment

```bash
# Build and run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f
```

## User Accounts

| Username | Password | Purpose |
|----------|----------|---------|
| pwau1    | test123  | Desktop user |
| pwau2    | test123  | Mobile user 1 |
| pwau3    | test123  | Mobile user 2 |

## Usage

1. **Install as PWA**
   - Open the app in Chrome/Firefox
   - Click the install icon in the address bar
   - Install as a desktop app

2. **Enable Notifications**
   - Login with any user account
   - Grant notification permissions when prompted
   - FCM token will be automatically registered

3. **Send Notifications**
   - Click "Send Notification" button
   - All other logged-in users will receive the notification
   - Check both desktop and mobile devices

## Deployment on Ubuntu LXC + HAProxy

### Prerequisites

```bash
# Update system
sudo apt update && sudo apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
```

### SSL Certificate Setup

```bash
# Create SSL directory
mkdir -p ssl

# Generate self-signed certificate (for testing)
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout ssl/key.pem \
  -out ssl/cert.pem \
  -subj "/C=US/ST=State/L=City/O=Organization/CN=your-domain.com"

# OR use Let's Encrypt for production
sudo apt install certbot
sudo certbot certonly --standalone -d your-domain.com
sudo cp /etc/letsencrypt/live/your-domain.com/fullchain.pem ssl/cert.pem
sudo cp /etc/letsencrypt/live/your-domain.com/privkey.pem ssl/key.pem
```

### HAProxy Configuration

Add to your `/etc/haproxy/haproxy.cfg`:

```haproxy
frontend fcm_test_frontend
    bind *:80
    bind *:443 ssl crt /etc/ssl/certs/your-cert.pem
    redirect scheme https if !{ ssl_fc }
    default_backend fcm_test_backend

backend fcm_test_backend
    balance roundrobin
    server fcm_test 127.0.0.1:3000 check
```

### Deploy

```bash
# Clone and setup
git clone <your-repo>
cd fcm-test-pwa
cp .env.example .env
# Edit .env with your Firebase config

# Deploy
docker-compose up -d

# Check status
docker-compose ps
docker-compose logs
```

## Testing

1. **Desktop Testing**
   - Open app in Chrome
   - Install as PWA
   - Login as pwau1
   - Send test notifications

2. **Mobile Testing**
   - Open app on mobile browsers
   - Install as PWA
   - Login as pwau2 and pwau3 on different devices
   - Test cross-device notifications

## Troubleshooting

- **Notifications not working**: Check Firebase configuration and service worker
- **PWA not installing**: Ensure site is served over HTTPS
- **Docker issues**: Check logs with `docker-compose logs`
- **HAProxy issues**: Verify SSL certificates and backend connectivity

## Security Notes

- Change default passwords in production
- Use proper SSL certificates
- Implement rate limiting for notifications
- Consider using a database for token storage in production