DEV Community: Bipin C

Safe Remote Server Reboot Guide

Bipin C — Fri, 23 Jan 2026 18:40:15 +0000

For Ubuntu Desktop with Docker and Cloudflare Tunnel

This guide ensures your remote server comes back online automatically after a reboot when you have no physical access to the machine.

Prerequisites

Your server should have:

Docker with containers using restart: unless-stopped
SSH server enabled
Cloudflare Tunnel for remote SSH access
(Ubuntu Desktop) Auto-login configured

Pre-Reboot Checklist

Run these commands on the server via SSH before rebooting.

1. Check Docker Starts on Boot

sudo systemctl is-enabled docker

Expected: enabled

If not enabled:

sudo systemctl enable docker

2. Check SSH Starts on Boot

sudo systemctl is-enabled ssh

Expected: enabled

If not enabled:

sudo systemctl enable ssh

3. Check Container Restart Policies

docker inspect --format '  - {{.Name}}: {{.HostConfig.RestartPolicy.Name}}' $(docker ps -q)

Expected: All containers should show unless-stopped or always

4. (Ubuntu Desktop Only) Configure Auto-Login

Check if you have a desktop environment:

sudo systemctl status gdm3

If GDM is active (Ubuntu Desktop), configure auto-login:

sudo nano /etc/gdm3/custom.conf

Add under [daemon]:

[daemon]
AutomaticLoginEnable=True
AutomaticLogin=your-username

Apply changes:

sudo systemctl restart gdm3

Verify configuration:

cat /etc/gdm3/custom.conf

Note: The keyring warnings (gkr-pam: couldn't unlock the login keyring) are normal and won't affect SSH or Docker.

Quick Verification Script

Run this single script to check everything:

echo "=== Pre-Reboot Check ==="
echo "Docker enabled: $(sudo systemctl is-enabled docker)"
echo "SSH enabled: $(sudo systemctl is-enabled ssh)"
echo ""
echo "Running containers:"
docker ps --format "  - {{.Names}}: {{.Status}}"
echo ""
echo "Restart policies:"
docker inspect --format '  - {{.Name}}: {{.HostConfig.RestartPolicy.Name}}' $(docker ps -q) 2>/dev/null || echo "  No containers running"

Expected output:

=== Pre-Reboot Check ===
Docker enabled: enabled
SSH enabled: enabled

Running containers:
  - n8n-cloudflared: Up 33 hours
  - n8n-prod: Up 33 hours (healthy)
  - n8n-dev: Up 33 hours (healthy)
  - n8n-postgres-prod: Up 33 hours (healthy)
  - n8n-postgres-dev: Up 33 hours (healthy)
  - cloudflared: Up 36 hours

Restart policies:
  - /n8n-cloudflared: unless-stopped
  - /n8n-prod: unless-stopped
  - /n8n-dev: unless-stopped
  - /n8n-postgres-prod: unless-stopped
  - /n8n-postgres-dev: unless-stopped
  - /cloudflared: unless-stopped

Safe to Reboot Checklist

Check	Required Status
Docker enabled on boot	`enabled`
SSH enabled on boot	`enabled`
All containers restart policy	`unless-stopped` or `always`
Auto-login (Ubuntu Desktop)	Configured for your user

Reboot Procedure

Step 1: Reboot the Server

sudo reboot

Your SSH session will disconnect immediately.

Step 2: Wait

Wait 2-3 minutes for:

Server to boot
Auto-login to complete (Ubuntu Desktop)
Docker service to start
Containers to start
Cloudflare Tunnel to establish connection

Step 3: Reconnect

ssh myserver

Step 4: Verify

Once connected, verify all containers are running:

docker ps

All containers should show Up X minutes status.

Troubleshooting

Can't reconnect after 5 minutes

Possible Cause	Solution
Docker didn't start	Needs physical access to check
Stuck at login screen	Auto-login not configured (Ubuntu Desktop)
Tunnel container failed	Check with `docker ps` when you regain access
Network/ISP issue	Wait and retry

Preventive Test (Optional)

Before rebooting, test that containers restart properly:

# Stop all containers
docker stop $(docker ps -q)

# Wait a few seconds
sleep 5

# Check if they auto-restart (they won't - you need to start them manually after stop)
# This is expected - "unless-stopped" only auto-starts after daemon restart, not after manual stop

# Start them manually for this test
cd ~/cloudflare-tunnel && docker compose up -d
cd ~/n8n-stack && docker compose up -d

# Verify
docker ps

Docker User Permissions

If Docker requires sudo, add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Verify:

docker ps

This persists across reboots. The newgrp command is only needed for the current session.

Summary

Safe to reboot when:

✅ sudo systemctl is-enabled docker → enabled
✅ sudo systemctl is-enabled ssh → enabled
✅ All containers have restart: unless-stopped
✅ (Ubuntu Desktop) Auto-login configured

Reboot command:

sudo reboot

Reconnect after 2-3 minutes:

ssh myserver

Multi-Instance n8n Self-Hosting Guide

Bipin C — Thu, 22 Jan 2026 15:04:32 +0000

Docker, PostgreSQL, and Cloudflare Zero Trust Tunnels

Version: 2.0

Last Updated: January 2026

Target Audience: Development Team

This guide provides production-grade configurations for running multiple isolated n8n instances (Production and Development) on a remote Ubuntu server using Docker, with secure external access through Cloudflare Zero Trust tunnels. Each instance has its own database, encryption key, and subdomain.

Prerequisites: Remote Server Access

This guide assumes you have:

✅ A remote Ubuntu server with Docker installed
✅ SSH access to the server via Cloudflare Tunnel
✅ SSH key authentication configured
✅ A domain managed by Cloudflare

To connect to your server:

ssh myserver

Note: All commands in the "SERVER" sections should be run after SSHing into your server. Commands marked "CLIENT" are run on your local machine.

Setup your SSH server access

Follow this guide to setup cloudflare tunnel SSH connection to your own server (Prerequisite) -> Guide

Architecture Overview
Tunnel Strategy
Ubuntu Desktop Server Preparation
Create n8n Tunnel in Cloudflare
Directory and File Setup
Environment Variables Configuration
Docker Compose Configuration
Configure Public Hostnames
Securing the Development Instance
Deployment
First-Time n8n Setup
Verification and Testing
Backup Procedures
Troubleshooting
Quick Reference

1. Architecture Overview

System Architecture

Key Design Principles

Principle	Implementation
Data Isolation	Separate PostgreSQL databases per n8n instance
Credential Isolation	Unique encryption keys per instance
Network Segmentation	Internal backend networks for databases
Zero Trust Access	Cloudflare Access protects dev instance
No Port Exposure	All access through Cloudflare Tunnels
Separate Tunnels	SSH tunnel independent from n8n tunnel

2. Tunnel Strategy

You already have a Cloudflare Tunnel running for SSH access. For n8n, we'll create a separate tunnel because:

SSH Tunnel	n8n Tunnel
Uses `network_mode: host`	Uses Docker network
Routes to `localhost:22`	Routes to container names (`n8n-prod:5678`)
Runs standalone	Runs in docker-compose with n8n
Already configured ✓	Will configure now

Your tunnels after setup:

Tunnel	Purpose	Hostnames
Existing (SSH)	Remote server access	`ssh.yourdomain.com`
New (n8n)	n8n web interfaces	`n8n-prod.yourdomain.com`, `n8n-dev.yourdomain.com`

3. Ubuntu Desktop Server Preparation

Run these commands on SERVER (via SSH)

ssh myserver

3.1 Disable Sleep/Suspend (If Ubuntu Desktop)

Skip this section if running Ubuntu Server (headless).

# Mask sleep targets
sudo systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target

# Configure logind
sudo nano /etc/systemd/logind.conf

Add:

[Login]
HandleLidSwitch=ignore
HandleLidSwitchExternalPower=ignore
HandleLidSwitchDocked=ignore
HandlePowerKey=ignore
HandleSuspendKey=ignore
IdleAction=ignore

Apply:

sudo systemctl restart systemd-logind.service

For GNOME desktop:

gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-ac-type 'nothing'
gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-ac-timeout 0
gsettings set org.gnome.desktop.session idle-delay 0

3.2 Verify Docker Installation

docker --version
docker compose version

If Docker is not installed, see Appendix A: Docker Installation.

4. Create n8n Tunnel in Cloudflare

Do this in your web browser (on CLIENT)

Open Cloudflare Zero Trust Dashboard
Go to Networks → Tunnels
Click Create a tunnel
Select Cloudflared as connector type
Name it: n8n-stack (or similar)
Select Docker as environment
Copy the token from the command shown (starts with eyJ...)

Save this token - you'll add it to your .env file in the next section.

Don't configure public hostnames yet - we'll do that after deployment.

5. Directory and File Setup

Run these commands on SERVER (via SSH)

ssh myserver

5.1 Create Project Directory

mkdir -p ~/n8n-stack
cd ~/n8n-stack

5.2 Create .gitignore

cat > .gitignore << 'EOF'
.env
*.backup
*.dump
*.sql
*.log
EOF

5.3 Directory Structure

After setup, your directory will look like:

~/n8n-stack/
├── docker-compose.yml    # Service definitions
├── .env                  # Secrets (chmod 600)
├── .gitignore            # Excludes .env from git
└── backup.sh             # Backup script (optional)

6. Environment Variables Configuration

Run these commands on SERVER (via SSH)

6.1 Generate Secure Values

cd ~/n8n-stack

# Generate encryption keys (save these!)
echo "Production Encryption Key: $(openssl rand -hex 32)"
echo "Development Encryption Key: $(openssl rand -hex 32)"

# Generate database passwords
echo "Production DB Password: $(openssl rand -base64 24)"
echo "Development DB Password: $(openssl rand -base64 24)"

Copy these values - you'll need them for the .env file.

6.2 Create Environment File

nano .env

Add the following (replace placeholders with your values):

# ============================================
# PRODUCTION DATABASE
# ============================================
POSTGRES_PROD_USER=n8n_prod
POSTGRES_PROD_PASSWORD=YOUR_GENERATED_PROD_DB_PASSWORD
POSTGRES_PROD_DB=n8n_production

# ============================================
# DEVELOPMENT DATABASE
# ============================================
POSTGRES_DEV_USER=n8n_dev
POSTGRES_DEV_PASSWORD=YOUR_GENERATED_DEV_DB_PASSWORD
POSTGRES_DEV_DB=n8n_development

# ============================================
# n8n PRODUCTION
# ============================================
N8N_PROD_HOST=n8n-prod.yourdomain.com
N8N_PROD_ENCRYPTION_KEY=YOUR_GENERATED_PROD_ENCRYPTION_KEY

# ============================================
# n8n DEVELOPMENT
# ============================================
N8N_DEV_HOST=n8n-dev.yourdomain.com
N8N_DEV_ENCRYPTION_KEY=YOUR_GENERATED_DEV_ENCRYPTION_KEY

# ============================================
# SHARED CONFIGURATION
# ============================================
TIMEZONE=Asia/Kolkata

# ============================================
# CLOUDFLARE TUNNEL (n8n tunnel, NOT SSH tunnel)
# ============================================
TUNNEL_TOKEN=YOUR_N8N_TUNNEL_TOKEN_FROM_STEP_4

Replace:

yourdomain.com → Your actual domain
YOUR_GENERATED_* → Values from step 6.1
YOUR_N8N_TUNNEL_TOKEN_FROM_STEP_4 → Token from Cloudflare dashboard
TIMEZONE → Your timezone (e.g., America/New_York, Europe/London)

6.3 Secure the File

chmod 600 .env
ls -la .env
# Should show: -rw------- (only owner can read/write)

6.4 Critical Warnings

⚠️ ENCRYPTION KEY WARNINGS

Set keys BEFORE first launch - they're stored in the database on first run

NEVER change keys after credentials are saved - you'll lose all stored credentials permanently

Back up your .env file securely - without encryption keys, credential recovery is impossible

Use DIFFERENT keys for prod and dev - prevents cross-instance issues

7. Docker Compose Configuration

Run on SERVER (via SSH)

cd ~/n8n-stack
nano docker-compose.yml

Paste the complete configuration:

services:
  # ============================================
  # PRODUCTION INSTANCE
  # ============================================
  postgres-prod:
    image: postgres:16-alpine
    container_name: n8n-postgres-prod
    restart: unless-stopped
    environment:
      - POSTGRES_USER=${POSTGRES_PROD_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PROD_PASSWORD}
      - POSTGRES_DB=${POSTGRES_PROD_DB}
    volumes:
      - postgres_prod_data:/var/lib/postgresql/data
    networks:
      - backend-prod
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_PROD_USER} -d ${POSTGRES_PROD_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

  n8n-prod:
    image: docker.n8n.io/n8nio/n8n:latest
    container_name: n8n-prod
    restart: unless-stopped
    environment:
      # Database Configuration
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres-prod
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=${POSTGRES_PROD_DB}
      - DB_POSTGRESDB_USER=${POSTGRES_PROD_USER}
      - DB_POSTGRESDB_PASSWORD=${POSTGRES_PROD_PASSWORD}
      # n8n Configuration
      - N8N_HOST=${N8N_PROD_HOST}
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - WEBHOOK_URL=https://${N8N_PROD_HOST}/
      - N8N_ENCRYPTION_KEY=${N8N_PROD_ENCRYPTION_KEY}
      - GENERIC_TIMEZONE=${TIMEZONE}
      # Performance Settings
      - NODE_OPTIONS=--max-old-space-size=2048
      - N8N_DEFAULT_BINARY_DATA_MODE=filesystem
      - EXECUTIONS_DATA_PRUNE=true
      - EXECUTIONS_DATA_MAX_AGE=336
      - EXECUTIONS_DATA_PRUNE_MAX_COUNT=50000
      # Monitoring
      - N8N_METRICS=true
    volumes:
      - n8n_prod_data:/home/node/.n8n
    networks:
      - frontend
      - backend-prod
    depends_on:
      postgres-prod:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:5678/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

  # ============================================
  # DEVELOPMENT INSTANCE
  # ============================================
  postgres-dev:
    image: postgres:16-alpine
    container_name: n8n-postgres-dev
    restart: unless-stopped
    environment:
      - POSTGRES_USER=${POSTGRES_DEV_USER}
      - POSTGRES_PASSWORD=${POSTGRES_DEV_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DEV_DB}
    volumes:
      - postgres_dev_data:/var/lib/postgresql/data
    networks:
      - backend-dev
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_DEV_USER} -d ${POSTGRES_DEV_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

  n8n-dev:
    image: docker.n8n.io/n8nio/n8n:latest
    container_name: n8n-dev
    restart: unless-stopped
    environment:
      # Database Configuration
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres-dev
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=${POSTGRES_DEV_DB}
      - DB_POSTGRESDB_USER=${POSTGRES_DEV_USER}
      - DB_POSTGRESDB_PASSWORD=${POSTGRES_DEV_PASSWORD}
      # n8n Configuration
      - N8N_HOST=${N8N_DEV_HOST}
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - WEBHOOK_URL=https://${N8N_DEV_HOST}/
      - N8N_ENCRYPTION_KEY=${N8N_DEV_ENCRYPTION_KEY}
      - GENERIC_TIMEZONE=${TIMEZONE}
      # Performance Settings (lower limits for dev)
      - NODE_OPTIONS=--max-old-space-size=1024
      - N8N_DEFAULT_BINARY_DATA_MODE=filesystem
      - EXECUTIONS_DATA_PRUNE=true
      - EXECUTIONS_DATA_MAX_AGE=72
      - EXECUTIONS_DATA_PRUNE_MAX_COUNT=5000
      # Monitoring
      - N8N_METRICS=true
    volumes:
      - n8n_dev_data:/home/node/.n8n
    networks:
      - frontend
      - backend-dev
    depends_on:
      postgres-dev:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:5678/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

  # ============================================
  # CLOUDFLARE TUNNEL (for n8n access)
  # ============================================
  cloudflared:
    image: cloudflare/cloudflared:latest
    container_name: n8n-cloudflared
    restart: unless-stopped
    command: tunnel --no-autoupdate run --token ${TUNNEL_TOKEN}
    networks:
      - frontend
    depends_on:
      - n8n-prod
      - n8n-dev

# ============================================
# NETWORKS
# ============================================
networks:
  frontend:
    driver: bridge
  backend-prod:
    driver: bridge
    internal: true
  backend-dev:
    driver: bridge
    internal: true

# ============================================
# VOLUMES
# ============================================
volumes:
  postgres_prod_data:
  postgres_dev_data:
  n8n_prod_data:
  n8n_dev_data:

Save and exit (Ctrl+O, Enter, Ctrl+X).

7.1 Configuration Differences: Prod vs Dev

Setting	Production	Development	Reason
`max-old-space-size`	2048 MB	1024 MB	Dev needs less memory
`EXECUTIONS_DATA_MAX_AGE`	336 hrs (14 days)	72 hrs (3 days)	Less retention for dev
`EXECUTIONS_DATA_PRUNE_MAX_COUNT`	50,000	5,000	Lower limits for dev

8. Configure Public Hostnames

Do this in your web browser (on CLIENT)

After the containers are running, configure the tunnel routing:

Go to Cloudflare Zero Trust Dashboard
Navigate to Networks → Tunnels
Click on your n8n-stack tunnel
Go to Public Hostname tab
Click Add a public hostname

Production Hostname

Field	Value
Subdomain	`n8n-prod`
Domain	Select your domain
Path	(leave empty)
Type	`HTTP`
URL	`n8n-prod:5678`

Click Save hostname.

Development Hostname

Click Add a public hostname again:

Field	Value
Subdomain	`n8n-dev`
Domain	Select your domain
Path	(leave empty)
Type	`HTTP`
URL	`n8n-dev:5678`

Click Save hostname.

Understanding Service URLs

URL	Correct?	Explanation
`n8n-prod:5678`	✅	Docker DNS resolves container names
`localhost:5678`	❌	Points to cloudflared container itself
`192.168.x.x:5678`	⚠️	Works but IP may change

9. Securing the Development Instance

Do this in your web browser (on CLIENT)

Protect the dev instance with Cloudflare Access so only you can access it.

9.1 Create Access Application

Go to Access → Applications
Click Add an application
Select Self-hosted
Configure:

Field	Value
Application name	`n8n Development`
Session duration	24 hours
Application domain	`n8n-dev.yourdomain.com`
Path	(leave empty)

Click Next

9.2 Create Access Policy

Field	Value
Policy name	`Dev Access`
Action	Allow

Include rule:

Selector: Emails
Value: your.email@example.com

Click Next, then Add application.

9.3 Configure Webhook Bypass

Webhooks need to receive external requests without authentication. Since Cloudflare Access doesn't support path-based rules within a policy, you must create a separate application for webhooks.

Create a Separate Webhook Application

Go to Access → Applications
Click Add an application
Select Self-hosted
Configure:

Field	Value
Application name	`n8n Dev Webhooks`
Session duration	24 hours
Application domain	`n8n-dev.yourdomain.com`
Path	`webhook/*`

Note: The Path field appears below the domain field when creating the application.

Click Next

Add Bypass Policy

Field	Value
Policy name	`Bypass All`
Action	Bypass

Include rule:

Selector: Everyone
Value: Everyone

Click Next → Add application

How It Works

You now have two applications for dev:

Application	Domain/Path	Policy
n8n Development	`n8n-dev.yourdomain.com`	Allow (your email)
n8n Dev Webhooks	`n8n-dev.yourdomain.com/webhook/*`	Bypass (Everyone)

Cloudflare evaluates the most specific path first, so:

Requests to /webhook/* → Bypass (no auth required)
All other requests → Require authentication

Note for Production: If your production instance (n8n-prod.yourdomain.com) is public without Access protection, webhooks work automatically — no bypass application needed.

10. Deployment

Run these commands on SERVER (via SSH)

ssh myserver
cd ~/n8n-stack

10.1 Validate Configuration

# Check .env file permissions
ls -la .env

# Validate docker-compose syntax
docker compose config --quiet && echo "✓ Configuration valid"

10.2 Start Services

docker compose up -d

10.3 Monitor Startup

# Watch all logs (Ctrl+C to exit)
docker compose logs -f

# Or watch specific service
docker compose logs -f n8n-prod

10.4 Verify All Containers Running

docker compose ps

Expected output:

NAME               STATUS                   PORTS
n8n-cloudflared    Up X minutes
n8n-dev            Up X minutes (healthy)
n8n-postgres-dev   Up X minutes (healthy)
n8n-postgres-prod  Up X minutes (healthy)
n8n-prod           Up X minutes (healthy)

Wait until all show (healthy) status (1-2 minutes).

11. First-Time n8n Setup

Do this in your web browser (on CLIENT)

11.1 Production Instance

Open https://n8n-prod.yourdomain.com
Create your owner account:
- Email
- First name, Last name
- Strong password
Complete the setup wizard

11.2 Development Instance

Open https://n8n-dev.yourdomain.com
Authenticate with Cloudflare Access (if configured)
Create a separate owner account

⚠️ Security: The first user to access each instance becomes the owner. Complete this immediately after deployment.

12. Verification and Testing

Run on SERVER (via SSH) unless noted

12.1 Test Container Health

# Test n8n health endpoints
docker exec n8n-prod wget -qO- http://localhost:5678/healthz
docker exec n8n-dev wget -qO- http://localhost:5678/healthz

12.2 Test Tunnel Connectivity

# Check cloudflared can reach n8n containers
docker exec n8n-cloudflared wget -qO- --timeout=5 http://n8n-prod:5678/healthz
docker exec n8n-cloudflared wget -qO- --timeout=5 http://n8n-dev:5678/healthz

12.3 Test Database Connectivity

# Check PostgreSQL
docker exec n8n-postgres-prod pg_isready -U n8n_prod -d n8n_production
docker exec n8n-postgres-dev pg_isready -U n8n_dev -d n8n_development

12.4 Test Webhooks

Do this from CLIENT

In n8n-prod, create a workflow with a Webhook node
Set method to POST
Copy the Production URL
Activate the workflow
Test from your client terminal:

curl -X POST https://n8n-prod.yourdomain.com/webhook-test/your-webhook-path \
  -H "Content-Type: application/json" \
  -d '{"test": "Hello from webhook!"}'

13. Backup Procedures

Run on SERVER (via SSH)

13.1 Manual Backup

cd ~/n8n-stack

# Production database
docker exec n8n-postgres-prod pg_dump -U n8n_prod -d n8n_production | gzip > backup_prod_$(date +%Y%m%d).sql.gz

# Development database
docker exec n8n-postgres-dev pg_dump -U n8n_dev -d n8n_development | gzip > backup_dev_$(date +%Y%m%d).sql.gz

# Environment file (CRITICAL - contains encryption keys)
cp .env .env.backup.$(date +%Y%m%d)

13.2 Automated Backup Script

cat > backup.sh << 'EOF'
#!/bin/bash
set -e

BACKUP_DIR="$HOME/n8n-backups"
DATE=$(date +%Y%m%d_%H%M%S)
RETENTION_DAYS=14

mkdir -p "$BACKUP_DIR"

echo "[$(date)] Starting backup..."

# Production
docker exec n8n-postgres-prod pg_dump -U n8n_prod -F c -d n8n_production > "$BACKUP_DIR/prod_$DATE.dump"

# Development  
docker exec n8n-postgres-dev pg_dump -U n8n_dev -F c -d n8n_development > "$BACKUP_DIR/dev_$DATE.dump"

# Environment file
cp ~/n8n-stack/.env "$BACKUP_DIR/env_$DATE.backup"

# Cleanup old backups
find "$BACKUP_DIR" -name "*.dump" -mtime +$RETENTION_DAYS -delete
find "$BACKUP_DIR" -name "*.backup" -mtime +$RETENTION_DAYS -delete

echo "[$(date)] Backup complete!"
ls -lh "$BACKUP_DIR" | tail -5
EOF

chmod +x backup.sh

13.3 Schedule Daily Backups

crontab -e

Add:

0 2 * * * /home/$USER/n8n-stack/backup.sh >> /home/$USER/n8n-stack/backup.log 2>&1

13.4 Restore from Backup

# Stop n8n first
docker compose stop n8n-prod

# Restore production database
gunzip -c backup_prod_20260122.sql.gz | docker exec -i n8n-postgres-prod psql -U n8n_prod -d n8n_production

# Start n8n
docker compose start n8n-prod

14. Troubleshooting

Common Issues

Issue	Cause	Solution
502 Bad Gateway	Container not healthy	`docker compose logs n8n-prod` - wait for healthy
Webhooks show localhost	WEBHOOK_URL wrong	Check `.env` has correct public URL
"Connection refused"	Database not ready	Wait for postgres to be healthy
Can't access dev instance	Not in Access policy	Add your email to Cloudflare Access
Tunnel not connecting	Wrong token	Verify TUNNEL_TOKEN in `.env`

Useful Commands

# Check all container status
docker compose ps

# View logs
docker compose logs -f cloudflared
docker compose logs -f n8n-prod

# Restart a service
docker compose restart n8n-prod

# Rebuild everything
docker compose down
docker compose up -d

# Check resource usage
docker stats

# Access container shell
docker exec -it n8n-prod /bin/sh

Network Debugging

# Test DNS resolution inside cloudflared
docker exec n8n-cloudflared nslookup n8n-prod
docker exec n8n-cloudflared nslookup n8n-dev

# Check network configuration
docker network ls
docker network inspect n8n-stack_frontend

15. Quick Reference

Your Endpoints

Service	URL
SSH Access	`ssh myserver`
n8n Production	`https://n8n-prod.yourdomain.com`
n8n Development	`https://n8n-dev.yourdomain.com`

Daily Operations (from CLIENT)

# Connect to server
ssh myserver

# Check status
cd ~/n8n-stack && docker compose ps

# View logs
docker compose logs -f

# Restart services
docker compose restart

# Update n8n
docker compose pull
docker compose up -d

File Locations (on SERVER)

File	Path
Docker Compose	`~/n8n-stack/docker-compose.yml`
Environment	`~/n8n-stack/.env`
Backups	`~/n8n-backups/`
SSH Tunnel	`~/cloudflare-tunnel/`

Important Reminders

✅ Backup encryption keys - Store .env securely offline
✅ Don't change encryption keys after first run
✅ Create owner accounts immediately after deployment
✅ Test webhooks before using in production
✅ Keep SSH tunnel separate from n8n tunnel

Appendix A: Docker Installation

If Docker is not installed on your server:

# Remove old versions
for pkg in docker.io docker-compose docker-compose-v2 podman-docker containerd runc; do
  sudo apt-get remove -y $pkg 2>/dev/null
done

# Add Docker repository
sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update

# Install Docker
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Enable on boot
sudo systemctl enable docker.service
sudo systemctl enable containerd.service

# Verify
docker run hello-world

Cloudflare Tunnel SSH Setup Guide

Bipin C — Thu, 22 Jan 2026 14:55:55 +0000

Complete Terminal-Based Remote Access with Docker

This guide enables SSH access to your server from anywhere using your terminal, with Cloudflare Tunnel running in Docker.

What you'll achieve: Run ssh myserver from any network and connect to your home/office server securely.

Architecture Overview

Security Benefits:

No ports exposed on your router
All traffic encrypted through Cloudflare
Server IP hidden from the internet
SSH key authentication (no passwords)
Cloudflare Access authentication layer

Prerequisites

Cloudflare account (free tier works)
Domain name with DNS managed by Cloudflare
Server: Ubuntu with Docker installed
Client: macOS, Linux, or Windows machine

PART 1: SERVER SETUP

Run all commands in this section on your server.

Step 1: Install SSH Server

Ubuntu may not have SSH server installed by default.

# Update package list
sudo apt update

# Install OpenSSH server
sudo apt install openssh-server -y

# Start and enable it
sudo systemctl start ssh
sudo systemctl enable ssh

# Verify it's running
sudo systemctl status ssh

You should see: Active: active (running)

Verify it's listening on port 22:

sudo ss -tlnp | grep :22

Expected output:

LISTEN 0  128  0.0.0.0:22  0.0.0.0:*  users:(("sshd",pid=xxxx,fd=3))

Step 2: Create Tunnel in Cloudflare Dashboard

Open Cloudflare Zero Trust Dashboard
Go to Networks → Tunnels
Click Create a tunnel
Select Cloudflared as connector type
Name your tunnel (e.g., home-server)
Select Docker as your environment
Cloudflare shows a command like:

   docker run cloudflare/cloudflared:latest tunnel --no-autoupdate run --token eyJhIjoiNWFi...

Copy the token (the long string after --token)

Step 3: Create Docker Compose Configuration

Create a directory for your tunnel:

mkdir -p ~/cloudflare-tunnel
cd ~/cloudflare-tunnel

Create the environment file:

nano .env

Add your token:

TUNNEL_TOKEN=eyJhIjoiNWFi...paste-your-full-token-here...

Save (Ctrl+O, Enter) and exit (Ctrl+X).

Secure the file:

chmod 600 .env

Create the Docker Compose file:

nano docker-compose.yml

Add this configuration:

services:
  cloudflared:
    image: cloudflare/cloudflared:latest
    container_name: cloudflared
    restart: unless-stopped
    command: tunnel --no-autoupdate run --token ${TUNNEL_TOKEN}
    network_mode: host

Save and exit.

Important: network_mode: host is required so the container can access the host's SSH on port 22.

Step 4: Start the Tunnel

docker compose up -d

Verify it's running:

docker compose ps

Expected output:

NAME          IMAGE                          STATUS
cloudflared   cloudflare/cloudflared:latest  Up X minutes

Check logs to confirm connection:

docker compose logs -f cloudflared

Look for: Registered tunnel connection or Connection registered

Press Ctrl+C to exit logs.

Step 5: Add SSH Public Hostname

Back in Cloudflare Dashboard:

Go to Networks → Tunnels
Click on your tunnel name (should show "HEALTHY")
Click Public Hostname tab
Click Add a public hostname
Configure:

Field	Value
Subdomain	`ssh` (or any name you prefer)
Domain	Select your domain from dropdown
Type	SSH
URL	`localhost:22`

Click Save hostname

Your SSH endpoint is now: ssh.yourdomain.com

Step 6: Create Access Application

This adds authentication before anyone can connect.

In Cloudflare Zero Trust Dashboard:

Go to Access → Applications
Click Add an application
Select Self-hosted
Configure:

Field	Value
Application name	SSH Access
Session duration	24 hours
Application domain	`ssh.yourdomain.com`

Click Next

Add Access Policy:

Policy name: Allow SSH
Action: Allow
Add a rule:
- Selector: Emails
- Value: your.email@example.com
Click Next
Leave advanced settings as default
Click Add application

PART 2: CLIENT SETUP

Run all commands in this section on your client machine.

Step 7: Install SSH Client

macOS

SSH client is pre-installed. Verify:

ssh -V

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install openssh-client -y

# Verify
ssh -V

Windows

Option 1: Via Settings

Settings → Apps → Optional Features → Add a feature → OpenSSH Client → Install

Option 2: PowerShell (Admin)

Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0

Verify:

ssh -V

Step 8: Install cloudflared

macOS

brew install cloudflared

Linux (Ubuntu/Debian)

curl -L --output cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared.deb

Windows

winget install --id Cloudflare.cloudflared

Or download from: https://github.com/cloudflare/cloudflared/releases/latest

Verify installation:

cloudflared --version

Step 9: Generate SSH Key

ssh-keygen -t ed25519 -C "your-email@example.com"

When prompted:

File location: Press Enter to accept default (~/.ssh/id_ed25519)
Passphrase: Enter a password (recommended) or leave empty

This creates:

~/.ssh/id_ed25519 — Private key (keep secret, never share)
~/.ssh/id_ed25519.pub — Public key (goes to server)

Step 10: Configure SSH

Create/edit your SSH config:

macOS / Linux:

mkdir -p ~/.ssh
nano ~/.ssh/config

Windows (PowerShell):

mkdir -Force $env:USERPROFILE\.ssh
notepad $env:USERPROFILE\.ssh\config

Add this configuration:

Host myserver
    HostName ssh.yourdomain.com
    User your-linux-username
    ProxyCommand cloudflared access ssh --hostname %h
    IdentityFile ~/.ssh/id_ed25519

Replace:

myserver → Any alias you want (e.g., homelab, workserver)
ssh.yourdomain.com → Your subdomain from Step 5
your-linux-username → Your username on the server

Save and exit.

Step 11: Copy Public Key to Server

First, connect to server with password:

ssh myserver

You'll go through:

Cloudflare authentication (browser opens, enter email, get code)
Linux password prompt

Once connected on the server, set up the authorized_keys:

# Create .ssh directory
mkdir -p ~/.ssh
chmod 700 ~/.ssh

# Open authorized_keys
nano ~/.ssh/authorized_keys

On your client (new terminal window), display your public key:

cat ~/.ssh/id_ed25519.pub

Copy the entire output (starts with ssh-ed25519 ...).

Paste it into the server's authorized_keys file, save and exit.

Set correct permissions:

chmod 600 ~/.ssh/authorized_keys

Exit the server:

exit

Step 12: Test Key Authentication

ssh myserver

This time it should:

Go through Cloudflare authentication (if session expired)
Connect directly using your SSH key — no password prompt!

Step 13: (Optional) Disable Password Authentication

Once key authentication works, disable passwords for better security.

On SERVER:

sudo nano /etc/ssh/sshd_config

Find and change (or add):

PasswordAuthentication no
PubkeyAuthentication yes

Restart SSH:

sudo systemctl restart ssh

Warning: Make sure key auth works before doing this, or you could lock yourself out!

Quick Reference

Server Commands

Task	Command
Check tunnel status	`docker compose ps`
View tunnel logs	`docker compose logs -f cloudflared`
Restart tunnel	`docker compose restart cloudflared`
Stop tunnel	`docker compose down`
Start tunnel	`docker compose up -d`
Update cloudflared	`docker compose pull && docker compose up -d`
Check SSH status	`sudo systemctl status ssh`
Restart SSH	`sudo systemctl restart ssh`

Client Commands

Task	Command
Connect to server	`ssh myserver`
Connect with verbose	`ssh -v myserver`
Clear Cloudflare auth	`cloudflared access logout`
View public key	`cat ~/.ssh/id_ed25519.pub`

File Structure Summary

Server

~/cloudflare-tunnel/
├── docker-compose.yml
└── .env                    # chmod 600

~/.ssh/
└── authorized_keys         # chmod 600 (contains client's public key)

Client

~/.ssh/
├── config                  # SSH configuration
├── id_ed25519              # Private key (never share!)
└── id_ed25519.pub          # Public key (copied to server)

Troubleshooting

Tunnel shows "INACTIVE" in Cloudflare dashboard

# On SERVER
docker compose ps
docker compose logs cloudflared
docker compose restart cloudflared

"Connection refused"

# On SERVER - Check SSH is running
sudo systemctl status ssh

# Check cloudflared is using host network
docker inspect cloudflared | grep NetworkMode
# Should show: "NetworkMode": "host"

"Permission denied" after setting up keys

# On SERVER - Check permissions
ls -la ~/.ssh/
# authorized_keys should be -rw------- (600)
# .ssh directory should be drwx------ (700)

# Fix if needed
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

Browser never opens for Cloudflare auth

# On CLIENT
cloudflared access login ssh.yourdomain.com

Session expired / keeps asking to authenticate

# On CLIENT
cloudflared access logout
ssh myserver

Verify everything is working

# On CLIENT - Connect with verbose output
ssh -v myserver

Complete Configuration Files

Server: docker-compose.yml

services:
  cloudflared:
    image: cloudflare/cloudflared:latest
    container_name: cloudflared
    restart: unless-stopped
    command: tunnel --no-autoupdate run --token ${TUNNEL_TOKEN}
    network_mode: host

Server: .env

TUNNEL_TOKEN=eyJhIjoiNWFiY2...your-full-token-from-cloudflare...

Client: ~/.ssh/config

Host myserver
    HostName ssh.yourdomain.com
    User your-linux-username
    ProxyCommand cloudflared access ssh --hostname %h
    IdentityFile ~/.ssh/id_ed25519

Summary Checklist

Server Setup

[ ] SSH server installed and running
[ ] Cloudflare tunnel created in dashboard
[ ] Docker compose file created with network_mode: host
[ ] Tunnel running (docker compose up -d)
[ ] Public hostname added (Type: SSH, URL: localhost:22)
[ ] Access application created with email policy
[ ] Client's public key added to ~/.ssh/authorized_keys

Client Setup

[ ] SSH client installed
[ ] cloudflared installed
[ ] SSH key generated (~/.ssh/id_ed25519)
[ ] SSH config created with ProxyCommand and IdentityFile
[ ] Public key copied to server

Test

[ ] ssh myserver connects successfully
[ ] No password prompt (key auth working)

# Self-Hosted Push Notifications Part-8

Bipin C — Wed, 22 Oct 2025 12:15:35 +0000

Self-Hosted Push Notifications Specification

Part 8: Complete Reference & FAQ

Version: 1.0
Last Updated: October 2025
Prerequisites: Part 7: Best Practices, Security & Optimization
Author: Bunty9
License: MIT (Free to use and adapt)

Complete API Reference
Browser Compatibility Matrix
Frequently Asked Questions (FAQ)
Troubleshooting Guide
Migration Guides
Glossary of Terms
Additional Resources
Specification Summary

Complete API Reference

Backend Endpoints

POST /api/push/subscribe

Subscribe to push notifications.

Request:

{
  "endpoint": "https://fcm.googleapis.com/fcm/send/...",
  "keys": {
    "p256dh": "BGt...",
    "auth": "abc..."
  },
  "userAgent": "Mozilla/5.0..."
}

Response:

{
  "success": true,
  "message": "Subscribed successfully",
  "data": {
    "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
    "deviceId": "web-abc123",
    "deviceName": "Chrome on macOS"
  }
}

Status Codes:

200 OK - Subscription successful
400 Bad Request - Invalid request body
401 Unauthorized - Authentication required
429 Too Many Requests - Rate limit exceeded

POST /api/push/unsubscribe

Unsubscribe from push notifications.

Request:

{
  "endpoint": "https://fcm.googleapis.com/fcm/send/..."
}

Response:

{
  "success": true,
  "message": "Unsubscribed successfully"
}

GET /api/push/devices

Get all devices subscribed for the authenticated user.

Response:

{
  "success": true,
  "count": 3,
  "data": {
    "devices": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "deviceId": "web-abc123",
        "deviceName": "Chrome on macOS",
        "browser": "Chrome",
        "os": "macOS",
        "deviceType": "desktop",
        "isActive": true,
        "lastUsedAt": "2025-10-22T10:30:00Z",
        "createdAt": "2025-10-01T08:00:00Z"
      }
    ]
  }
}

POST /api/push/test/:userId (Admin Only)

Send a test notification to a specific user.

Request:

{
  "title": "Test Notification",
  "body": "This is a test notification",
  "url": "/",
  "deviceId": "web-abc123" // Optional: target specific device
}

Response:

{
  "success": true,
  "message": "Test notification sent successfully",
  "data": {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "deviceId": "web-abc123"
  }
}

Frontend API

navigator.serviceWorker.register()

// Usage
const registration = await navigator.serviceWorker.register('/sw.js');
console.log('Service worker registered:', registration);

Notification.requestPermission()

Request notification permission from user.

// Usage
const permission = await Notification.requestPermission();
console.log('Permission:', permission); // "granted", "denied", or "default"

Returns: Promise<NotificationPermission>

registration.pushManager.subscribe()

Subscribe to push notifications with VAPID key.

// Usage
const subscription = await registration.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY)
});

console.log('Subscription:', subscription.toJSON());

Returns: Promise<PushSubscription>

registration.showNotification()

Show a notification (from service worker).

// Usage
self.registration.showNotification('Title', {
  body: 'Notification body',
  icon: '/icon-192x192.png',
  badge: '/icon-72x72.png',
  data: { url: '/bookings/123' },
  actions: [
    { action: 'view', title: 'View', icon: '/view-icon.png' },
    { action: 'dismiss', title: 'Dismiss', icon: '/dismiss-icon.png' }
  ]
});

Push Payload Schema

interface PushPayload {
  // Required
  title: string;                      // Max 65 characters
  body: string;                       // Max 240 characters

  // Optional display
  icon?: string;                      // URL to icon (192x192 recommended)
  badge?: string;                     // URL to badge (72x72 recommended)
  image?: string;                     // URL to large image
  tag?: string;                       // Notification grouping ID

  // Behavior
  requireInteraction?: boolean;       // Keep until dismissed
  silent?: boolean;                   // Suppress sound
  vibrate?: number[];                 // Vibration pattern [ms]
  renotify?: boolean;                 // Re-alert on tag update

  // Navigation
  url?: string;                       // URL to open on click

  // Custom data
  data?: {
    [key: string]: any;               // Custom payload data
  };

  // Actions (max 2 on mobile, 4 on desktop)
  actions?: Array<{
    action: string;                   // Action identifier
    title: string;                    // Button text
    icon?: string;                    // Button icon
  }>;
}

Browser Compatibility Matrix

Desktop Browsers

Feature	Chrome	Firefox	Safari	Edge	Opera
Service Workers	✅ 40+	✅ 44+	✅ 11.1+	✅ 17+	✅ 27+
Push API	✅ 42+	✅ 44+	✅ 16+	✅ 17+	✅ 29+
Notification API	✅ 42+	✅ 44+	✅ 16+	✅ 17+	✅ 29+
Background Sync	✅ 49+	❌ No	❌ No	✅ 79+	✅ 36+
Notification Actions	✅ 48+	❌ No	⚠️ Limited	✅ 18+	✅ 35+

Mobile Browsers

Feature	Chrome (Android)	Firefox (Android)	Safari (iOS)	Samsung Internet
Service Workers	✅ 40+	✅ 44+	✅ 11.3+	✅ 4.0+
Push API	✅ 42+	✅ 44+	⚠️ 16.4+	✅ 4.0+
Notification API	✅ 42+	✅ 44+	⚠️ Limited	✅ 4.0+
PWA Required	❌ No	❌ No	✅ Yes	❌ No

Important Notes

iOS Safari:

Push notifications only work if app is added to home screen (PWA)
Must open app from home screen icon (not browser)
Requires iOS 16.4+ and Safari 16.4+
No support for notification actions
Limited customization

Detection Code:

const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent);
const isStandalone = window.navigator.standalone;
const isPWA = window.matchMedia('(display-mode: standalone)').matches;

if (isIOS && !isStandalone && !isPWA) {
  // Show "Add to Home Screen" instructions
  showPWAInstallPrompt();
}

Frequently Asked Questions (FAQ)

General Questions

Q: Do I need FCM or other third-party services?

A: No! This is a completely self-hosted solution. The browser's push service (FCM for Chrome, Mozilla Push for Firefox) is used internally by the browser, but you don't need an FCM account or API key. VAPID keys are all you need.

Q: How much does it cost to run?

A: $0 for push notifications. You only pay for:

Your server infrastructure (backend + database)
Domain and SSL certificate
Optional monitoring tools

No per-message costs, no quotas, no vendor lock-in.

Q: What happens if my server goes down?

A: Notifications sent during downtime are lost. The Web Push Protocol has a TTL (Time To Live) of 30 days by default, but browser push services don't queue messages indefinitely. Implement:

High availability (multiple backend instances)
Health checks and auto-restart
Monitoring and alerting

Q: Can I send notifications to iOS users?

A: Yes, but with limitations:

Only works if app is added to home screen (PWA)
User must open app from home screen icon
Requires iOS 16.4+ and Safari 16.4+
No notification actions
About 30% of mobile users (as of 2025)

Consider fallback strategies like email or SMS for iOS users.

Technical Questions

Q: How do VAPID keys work?

A: VAPID (Voluntary Application Server Identification) uses asymmetric cryptography:

Private Key: Kept secret on your server, signs push messages
Public Key: Shared with browsers during subscription
Signature: Browser validates that push came from your server

Think of it like SSH keys or SSL certificates.

Q: Can I reuse VAPID keys across environments?

A: Not recommended. Use different keys for:

Development
Staging
Production

This prevents cross-environment issues and improves security.

Q: How many devices can a user have?

A: By default, 5 devices per user/admin. This is configurable:

// Change device limit
if count >= 10 { // Increase to 10
    return errors.New("device limit reached")
}

Each browser on each device counts as one subscription.

Q: What's the maximum notification size?

A: Approximately 4KB total payload. Recommendations:

Title: Max 65 characters
Body: Max 240 characters
Icon: URL only (image not embedded)
Keep data object small

Q: How fast are notifications delivered?

A: Typically < 1 second from your server to user's device:

Your server → Browser push service: ~50ms
Browser push service → User device: ~500ms
Service worker processing: ~50ms

Network conditions and device state affect delivery time.

Q: Can I send rich media notifications?

A: Yes! You can include:

✅ Icons (192x192 recommended)
✅ Badges (72x72)
✅ Images (any size, but keep < 1MB)
✅ Vibration patterns
✅ Action buttons (up to 4)
❌ Videos (not supported)
❌ Interactive forms (not supported)

Security Questions

Q: Is it secure?

A: Yes, if implemented correctly:

✅ VAPID authentication prevents spoofing
✅ HTTPS required for service workers
✅ End-to-end encryption (browser handles)
✅ User consent required
✅ Subscriptions tied to origin (can't spoof)

Follow security best practices in Part 7.

Q: Can someone steal my VAPID private key?

A: If compromised:

Attacker can send push notifications as your app
Rotate keys immediately (see Part 7)
Users will need to resubscribe
Monitor for unusual notification patterns

Store private keys securely:

Environment variables (not in code)
Secrets manager (AWS Secrets Manager, HashiCorp Vault)
Kubernetes secrets

Q: Can users unsubscribe?

A: Yes, users can:

Click "Unsubscribe" in your app UI
Revoke permissions in browser settings
Clear browser data (removes subscription)

Always provide an easy unsubscribe option.

Scaling Questions

Q: How many notifications can I send per second?

A: Depends on your infrastructure:

Setup	Notifications/second
Single server	~100-500
3 replicas	~300-1500
10 replicas	~1000-5000
With rate limiting	Depends on limits

Bottlenecks:

Database queries
HTTP connections to push services
Goroutine limits

Q: Do I need a queue system?

A: Optional, but recommended for:

High volume (>1000 notifications/second)
Guaranteed delivery with retries
Priority queuing
Rate limiting across multiple servers

Use Redis, RabbitMQ, or AWS SQS.

Q: How do I handle multiple backend replicas?

Database Connection Pooling: Prevents connection exhaustion
Stateless Services: No in-memory state
Worker Coordination: Use distributed locks (Redis) for background workers
Load Balancing: Round-robin or least-connections

See Part 5 for horizontal scaling strategies.

Troubleshooting Guide

Symptom: Notifications not showing up

Possible Causes:

Permission denied

   // Check permission
   console.log('Permission:', Notification.permission);

   // If "denied", user must manually enable in browser settings

Service worker not registered

   // Check registration
   navigator.serviceWorker.getRegistrations().then(regs => {
     console.log('Registrations:', regs);
   });

Subscription expired

   // Check subscription
   navigator.serviceWorker.ready.then(async reg => {
     const sub = await reg.pushManager.getSubscription();
     console.log('Subscription:', sub);
   });

Backend error

   # Check backend logs
   kubectl logs -f deployment/user-service | grep "Push"

Symptom: High failure rate

Debugging Steps:

-- Check error messages
SELECT
  error_message,
  http_status_code,
  COUNT(*) as count
FROM push_notification_logs
WHERE status = 'failed'
  AND sent_at > NOW() - INTERVAL '1 hour'
GROUP BY error_message, http_status_code
ORDER BY count DESC;

Common Solutions:

Error	Solution
410 Gone	Subscription expired (auto-handled)
403 Forbidden	Check VAPID keys
400 Bad Request	Validate payload format
429 Too Many Requests	Implement rate limiting

Symptom: Memory leak

Debugging:

# Check memory usage
go tool pprof http://localhost:6060/debug/pprof/heap

# Check goroutines
go tool pprof http://localhost:6060/debug/pprof/goroutine

Common Causes:

Goroutine leaks (not closing channels)
Database connection leaks
Unbounded caches

Symptom: Slow notification delivery

Debugging:

-- Check p95 latency
SELECT
  PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY (sent_at - created_at)) as p95_latency
FROM push_notification_logs
WHERE sent_at > NOW() - INTERVAL '1 hour';

Optimization:

Add database indexes
Increase connection pool size
Use goroutine pooling
Implement caching

Migration Guides

From FCM to Self-Hosted

Step 1: Generate VAPID Keys

npm install -g web-push
web-push generate-vapid-keys

Step 2: Update Backend

Remove FCM SDK
Install webpush-go
Implement PushService (see Part 2)

Step 3: Update Frontend

Remove FCM firebase-messaging-sw.js
Implement sw.js (see Part 4)
Update subscription flow

Step 4: Migrate Existing Subscriptions

-- Map FCM tokens to new subscriptions
-- Users will need to resubscribe
-- Consider grace period with both systems running

From OneSignal to Self-Hosted

Key Differences:

Feature	OneSignal	Self-Hosted
Setup Time	10 minutes	2-4 hours
Cost	Free tier, then $99+/mo	Infrastructure only
Vendor Lock-in	Yes	No
Customization	Limited	Complete
Analytics	Built-in	DIY (Prometheus)

Migration Steps: Same as FCM migration above.

Glossary of Terms

VAPID

Voluntary Application Server Identification. Authentication mechanism using public/private key pairs to verify push notification origin.

Service Worker

JavaScript file that runs in the background, separate from web pages. Enables push notifications, offline support, and background sync.

Push Subscription

Object containing endpoint URL and encryption keys that identifies a device for push delivery.

Endpoint

HTTPS URL provided by browser's push service (e.g., FCM, Mozilla Push) where notifications are sent.

p256dh

Public Key for Diffie-Hellman. Used to encrypt notification payloads.

auth

Authentication Secret. Used alongside p256dh for encryption.

TTL

Time To Live. How long push services keep notifications if device is offline (default: 30 days).

PWA

Progressive Web App. Web application that can be installed like a native app and supports offline functionality.

Goroutine

Lightweight thread in Go for concurrent execution.

GORM

Go Object-Relational Mapping. Database ORM library for Go.

JWT

JSON Web Token. Token-based authentication standard.

Additional Resources

Official Specifications

Web Push Protocol: RFC 8030
VAPID: RFC 8292
Service Workers: W3C Specification
Push API: MDN Web Docs
Notification API: MDN Web Docs

Libraries & Tools

Backend (Go):

webpush-go - Web Push Protocol implementation
Gin - HTTP web framework
GORM - ORM library

Frontend (JavaScript/TypeScript):

web-push - Node.js Web Push library
Workbox - Service worker toolkit
next-pwa - PWA plugin for Next.js

Testing:

Playwright - E2E testing
k6 - Load testing

Monitoring:

Prometheus - Metrics collection
Grafana - Visualization
Sentry - Error tracking

Community & Support

Stack Overflow: Tag [web-push] or [service-worker]
GitHub Discussions: Create discussions on this repo
MDN Web Docs: Comprehensive browser API documentation
Can I Use: Browser compatibility checker (caniuse.com)

Learning Resources

Service Worker Cookbook: serviceworke.rs
PWA Guide: web.dev/progressive-web-apps
Web Push Book: web-push-book.gauntface.com

Specification Summary

What You've Built

By following this 8-part specification, you've implemented:

✅ Complete self-hosted push notification system
✅ No third-party dependencies (FCM, OneSignal, etc.)
✅ Production-ready backend (Go with GORM)
✅ Production-ready frontend (Next.js with TypeScript)
✅ Service worker with background handling
✅ PWA manifest for installability
✅ Multi-device support (up to 5 per user)
✅ Advanced targeting (users, admins, roles, broadcast)
✅ Notification scheduling with background workers
✅ Rate limiting & throttling
✅ Batch processing for scalability
✅ Retry strategies with exponential backoff
✅ Docker & Kubernetes deployment configs
✅ Monitoring & alerting (Prometheus, Grafana)
✅ Health checks and error tracking
✅ Security best practices (VAPID, HTTPS, validation)
✅ Performance optimization (indexing, pooling, caching)
✅ Comprehensive testing (unit, integration, E2E, load)

Specification Parts Recap

Part	Title	Topics Covered
Part 1	Architecture & Setup	System overview, VAPID, database schema, project structure
Part 2	Backend Implementation	GORM models, PushService, controllers, routes, middleware
Part 3	Frontend Implementation	API routes, hooks, components, TypeScript types
Part 4	Service Worker & PWA	SW implementation, PWA manifest, action handlers, offline
Part 5	Advanced & Deployment	Targeting, scheduling, rate limiting, Docker, Kubernetes
Part 6	Monitoring & Debugging	Metrics, logging, profiling, health checks, alerting
Part 7	Best Practices & Security	Security, VAPID management, validation, optimization, testing
Part 8	Reference & FAQ	API reference, browser compatibility, FAQ, troubleshooting

Estimated Implementation Time

Component	Time Estimate
Setup & Architecture	2-4 hours
Backend Implementation	8-12 hours
Frontend Implementation	6-10 hours
Service Worker & PWA	4-6 hours
Testing & QA	6-8 hours
Deployment & Monitoring	4-6 hours
Documentation	2-4 hours
Total	32-50 hours

With AI assistance (agents), implementation time can be reduced by 50-70%.

Production Readiness Checklist

Before going live:

[ ] VAPID keys generated and secured
[ ] Database migrations applied
[ ] All environment variables configured
[ ] Service workers registered and tested
[ ] PWA manifest configured
[ ] SSL/HTTPS enabled
[ ] Rate limiting configured
[ ] Monitoring and alerting set up
[ ] Error tracking integrated (Sentry)
[ ] Health checks passing
[ ] Load testing completed (target throughput achieved)
[ ] Security audit passed
[ ] Backup strategy in place
[ ] Documentation complete
[ ] Team trained
[ ] Rollback plan prepared

Next Steps After Implementation

Monitor metrics for first 24 hours
Gather user feedback on notification experience
Optimize based on real-world usage patterns
A/B test notification content and timing
Iterate on targeting strategies
Scale infrastructure as needed
Plan key rotation (6-12 months)

Final Notes

This Specification is Open Source

Feel free to:

✅ Use this specification for your projects
✅ Adapt and modify as needed
✅ Share with your team
✅ Contribute improvements

Contributing

If you find issues or have improvements:

Open an issue on GitHub
Submit a pull request
Share your implementation stories
Help others in discussions

License

MIT License - Free to use, modify, and distribute.

Author

Researched and Implemented with ❤️ by Bunty9

Congratulations! 🎉

You've completed the Self-Hosted Push Notifications Specification.

You now have the knowledge and code to build a complete, production-ready push notification system without any third-party dependencies.

Happy coding! 🚀

# Self-Hosted Push Notifications Part-7

Bipin C — Wed, 22 Oct 2025 12:12:59 +0000

Self-Hosted Push Notifications Specification

Part 7: Best Practices, Security & Optimization

Version: 1.0
Last Updated: October 2025
Prerequisites: Part 6: Monitoring, Debugging & Troubleshooting
Author: Bunty9
License: MIT (Free to use and adapt)

Security Best Practices
VAPID Key Management
Input Validation
SQL Injection Prevention
Authentication & Authorization
Performance Optimization
Code Organization
Testing Strategies
Documentation Standards
Deployment Checklist

Security Best Practices

1. Secrets Management

❌ Bad Practice:

// Hardcoded secrets
const VAPIDPrivateKey = "BNw7fc1ayj3-Az-OJ8DrOj3EDAHCORwO_r3SsrpwkzQ"

✅ Good Practice:

// Load from environment
vapidPrivateKey := os.Getenv("VAPID_PRIVATE_KEY")
if vapidPrivateKey == "" {
    log.Fatal("VAPID_PRIVATE_KEY is required")
}

// Or from secrets manager
func loadVAPIDKeys() (string, string, error) {
    secretName := "vapid-keys"
    region := "us-east-1"

    sess, err := session.NewSession(&aws.Config{
        Region: aws.String(region),
    })
    if err != nil {
        return "", "", err
    }

    svc := secretsmanager.New(sess)
    input := &secretsmanager.GetSecretValueInput{
        SecretId: aws.String(secretName),
    }

    result, err := svc.GetSecretValue(input)
    if err != nil {
        return "", "", err
    }

    var secretData map[string]string
    json.Unmarshal([]byte(*result.SecretString), &secretData)

    return secretData["public_key"], secretData["private_key"], nil
}

2. Rate Limiting

Apply rate limiting at multiple levels:

// Per-user rate limiting
type UserRateLimiter struct {
    limiters map[string]*rate.Limiter
    mu       sync.RWMutex
}

// Global rate limiting
type GlobalRateLimiter struct {
    limiter *rate.Limiter
}

// IP-based rate limiting (for public endpoints)
type IPRateLimiter struct {
    limiters map[string]*rate.Limiter
    mu       sync.RWMutex
}

3. HTTPS Enforcement

// Redirect HTTP to HTTPS
func httpsRedirectMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        if c.Request.Header.Get("X-Forwarded-Proto") == "http" {
            httpsURL := "https://" + c.Request.Host + c.Request.RequestURI
            c.Redirect(http.StatusMovedPermanently, httpsURL)
            c.Abort()
            return
        }
        c.Next()
    }
}

4. CORS Configuration

// Strict CORS configuration
corsConfig := cors.Config{
    AllowOrigins: []string{
        "https://yourdomain.com",
        "https://app.yourdomain.com",
    },
    AllowMethods: []string{
        "GET", "POST", "PUT", "DELETE", "OPTIONS",
    },
    AllowHeaders: []string{
        "Origin", "Content-Type", "Authorization",
    },
    AllowCredentials: true,
    MaxAge:           12 * time.Hour,
}

router.Use(cors.New(corsConfig))

5. Content Security Policy

// Add CSP headers
func securityHeadersMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        c.Header("Content-Security-Policy",
            "default-src 'self'; "+
            "script-src 'self' 'unsafe-inline'; "+
            "style-src 'self' 'unsafe-inline'; "+
            "img-src 'self' data: https:;")
        c.Header("X-Content-Type-Options", "nosniff")
        c.Header("X-Frame-Options", "DENY")
        c.Header("X-XSS-Protection", "1; mode=block")
        c.Next()
    }
}

VAPID Key Management

Key Rotation Strategy

When to Rotate:

Every 6-12 months (scheduled)
Suspected key compromise
Team member departure
Security audit requirement

Rotation Process:

// 1. Generate new keys
newPrivateKey, newPublicKey, _ := webpush.GenerateVAPIDKeys()

// 2. Store new keys (keep old keys for transition period)
os.Setenv("VAPID_PUBLIC_KEY_NEW", newPublicKey)
os.Setenv("VAPID_PRIVATE_KEY_NEW", newPrivateKey)

// 3. Support both keys temporarily
func (ps *PushService) sendToSubscription(subscription models.PushSubscription, payload types.PushPayload) error {
    // Try new key first
    err := ps.sendWithKey(subscription, payload, ps.newVapidPrivateKey, ps.newVapidPublicKey)

    // Fallback to old key
    if err != nil {
        err = ps.sendWithKey(subscription, payload, ps.oldVapidPrivateKey, ps.oldVapidPublicKey)
    }

    return err
}

// 4. After transition period (e.g., 30 days), remove old keys

Key Storage Best Practices

❌ Never do this:

# Committed to git
git add .env
git commit -m "Add VAPID keys"

✅ Always do this:

# .gitignore
.env
.env.local
.env.production

# Kubernetes secrets
kubectl create secret generic vapid-keys \
  --from-literal=public-key='BOzzMgOMwVyuziwHiI8...' \
  --from-literal=private-key='BNw7fc1ayj3-Az-OJ8...'

# AWS Secrets Manager
aws secretsmanager create-secret \
  --name vapid-keys \
  --secret-string '{"public":"BOzz...","private":"BNw7..."}'

Input Validation

1. Subscription Endpoint Validation

func validateSubscriptionEndpoint(endpoint string) error {
    // Must be HTTPS
    if !strings.HasPrefix(endpoint, "https://") {
        return errors.New("endpoint must use HTTPS")
    }

    // Valid URL format
    u, err := url.Parse(endpoint)
    if err != nil {
        return fmt.Errorf("invalid endpoint URL: %w", err)
    }

    // Must be from trusted push services
    allowedHosts := []string{
        "fcm.googleapis.com",
        "updates.push.services.mozilla.com",
        "push.apple.com",
        "wns2-*.notify.windows.com",
    }

    hostAllowed := false
    for _, allowed := range allowedHosts {
        if strings.Contains(u.Host, allowed) || u.Host == allowed {
            hostAllowed = true
            break
        }
    }

    if !hostAllowed {
        return fmt.Errorf("endpoint host not allowed: %s", u.Host)
    }

    return nil
}

2. Payload Validation

func validatePushPayload(payload types.PushPayload) error {
    // Title required, max 65 characters
    if payload.Title == "" {
        return errors.New("title is required")
    }
    if len(payload.Title) > 65 {
        return errors.New("title must be 65 characters or less")
    }

    // Body required, max 240 characters
    if payload.Body == "" {
        return errors.New("body is required")
    }
    if len(payload.Body) > 240 {
        return errors.New("body must be 240 characters or less")
    }

    // URL validation (if provided)
    if payload.URL != "" {
        if !strings.HasPrefix(payload.URL, "/") && !strings.HasPrefix(payload.URL, "http") {
            return errors.New("URL must be relative or absolute")
        }
    }

    // Validate actions (max 2 on mobile, 4 on desktop)
    if len(payload.Actions) > 4 {
        return errors.New("maximum 4 actions allowed")
    }

    return nil
}

3. User Input Sanitization

import "html"

func sanitizePushPayload(payload *types.PushPayload) {
    // Escape HTML in title and body
    payload.Title = html.EscapeString(payload.Title)
    payload.Body = html.EscapeString(payload.Body)

    // Trim whitespace
    payload.Title = strings.TrimSpace(payload.Title)
    payload.Body = strings.TrimSpace(payload.Body)
}

SQL Injection Prevention

Use Parameterized Queries

❌ Vulnerable to SQL Injection:

// NEVER DO THIS
query := fmt.Sprintf("SELECT * FROM push_subscriptions WHERE user_id = '%s'", userID)
db.Raw(query).Scan(&subscriptions)

✅ Safe with Parameterized Queries:

// GORM automatically uses parameterized queries
db.Where("user_id = ?", userID).Find(&subscriptions)

// Raw query with parameters
db.Raw("SELECT * FROM push_subscriptions WHERE user_id = ?", userID).Scan(&subscriptions)

Input Validation for UUIDs

func validateUUID(id string) (uuid.UUID, error) {
    parsedUUID, err := uuid.Parse(id)
    if err != nil {
        return uuid.Nil, fmt.Errorf("invalid UUID format: %w", err)
    }
    return parsedUUID, nil
}

// Usage
func (ps *PushService) SendToUser(userIDStr string, payload types.PushPayload) error {
    userID, err := validateUUID(userIDStr)
    if err != nil {
        return err
    }

    // Safe to use
    var subscriptions []models.PushSubscription
    ps.db.Where("user_id = ?", userID).Find(&subscriptions)
    // ...
}

Authentication & Authorization

JWT Best Practices

// 1. Use strong secret keys (256+ bits)
jwtSecret := []byte(os.Getenv("JWT_SECRET"))
if len(jwtSecret) < 32 {
    log.Fatal("JWT_SECRET must be at least 32 characters")
}

// 2. Set appropriate expiration
claims := jwt.MapClaims{
    "sub":      userID,
    "iat":      time.Now().Unix(),
    "exp":      time.Now().Add(24 * time.Hour).Unix(), // 24 hours
    "isAdmin":  false,
}

// 3. Validate all claims
func validateJWT(tokenString string) (*jwt.Token, error) {
    token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
        // Validate signing method
        if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
            return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
        }
        return jwtSecret, nil
    })

    if err != nil {
        return nil, err
    }

    // Validate expiration
    if claims, ok := token.Claims.(jwt.MapClaims); ok && token.Valid {
        if exp, ok := claims["exp"].(float64); ok {
            if time.Unix(int64(exp), 0).Before(time.Now()) {
                return nil, errors.New("token expired")
            }
        }
    }

    return token, nil
}

Role-Based Access Control

// Define roles
const (
    RoleUser       = "user"
    RoleCaretaker  = "caretaker"
    RoleSpaceAdmin = "space_admin"
    RoleSuperAdmin = "super_admin"
)

// Check permissions
func (pc *PushController) SendTestNotification(c *gin.Context) {
    userRole, exists := c.Get("userRole")
    if !exists {
        c.JSON(http.StatusUnauthorized, gin.H{"error": "Unauthorized"})
        return
    }

    // Only super admins can send test notifications
    if userRole != RoleSuperAdmin {
        c.JSON(http.StatusForbidden, gin.H{"error": "Forbidden"})
        return
    }

    // Proceed with test notification...
}

Performance Optimization

1. Database Indexing

-- Essential indexes
CREATE INDEX CONCURRENTLY idx_push_subscriptions_user_active
ON push_subscriptions(user_id, is_active)
WHERE is_active = TRUE;

CREATE INDEX CONCURRENTLY idx_push_subscriptions_admin_active
ON push_subscriptions(admin_id, is_active)
WHERE is_active = TRUE;

CREATE INDEX CONCURRENTLY idx_push_notification_logs_sent_status
ON push_notification_logs(sent_at DESC, status);

-- Composite indexes for complex queries
CREATE INDEX CONCURRENTLY idx_push_subscriptions_composite
ON push_subscriptions(user_id, is_active, last_used_at DESC);

2. Connection Pooling

func setupDatabasePool(dsn string) (*gorm.DB, error) {
    db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{
        PrepareStmt: true, // Prepare statements
        Logger:      logger.Default.LogMode(logger.Silent),
    })
    if err != nil {
        return nil, err
    }

    sqlDB, err := db.DB()
    if err != nil {
        return nil, err
    }

    // Optimize connection pool
    sqlDB.SetMaxOpenConns(100)              // Max open connections
    sqlDB.SetMaxIdleConns(10)               // Max idle connections
    sqlDB.SetConnMaxLifetime(time.Hour)     // Max connection lifetime
    sqlDB.SetConnMaxIdleTime(10 * time.Minute) // Max idle time

    return db, nil
}

3. Caching Strategies

import "github.com/patrickmn/go-cache"

type CachedPushService struct {
    *PushService
    cache *cache.Cache
}

func NewCachedPushService(db *gorm.DB) *CachedPushService {
    return &CachedPushService{
        PushService: NewPushService(db),
        cache:       cache.New(5*time.Minute, 10*time.Minute),
    }
}

// Cache subscription lookups
func (cps *CachedPushService) GetUserSubscriptions(userID uuid.UUID) ([]models.PushSubscription, error) {
    cacheKey := fmt.Sprintf("user_subscriptions:%s", userID)

    // Try cache first
    if cached, found := cps.cache.Get(cacheKey); found {
        return cached.([]models.PushSubscription), nil
    }

    // Query database
    var subscriptions []models.PushSubscription
    err := cps.db.Where("user_id = ? AND is_active = ?", userID, true).
        Find(&subscriptions).Error

    if err != nil {
        return nil, err
    }

    // Cache for 5 minutes
    cps.cache.Set(cacheKey, subscriptions, cache.DefaultExpiration)

    return subscriptions, nil
}

// Invalidate cache on subscription changes
func (cps *CachedPushService) Subscribe(userID *uuid.UUID, adminID *uuid.UUID, req types.SubscribePushRequest) (*types.SubscribePushResponse, error) {
    resp, err := cps.PushService.Subscribe(userID, adminID, req)
    if err != nil {
        return nil, err
    }

    // Invalidate cache
    if userID != nil {
        cps.cache.Delete(fmt.Sprintf("user_subscriptions:%s", *userID))
    }
    if adminID != nil {
        cps.cache.Delete(fmt.Sprintf("admin_subscriptions:%s", *adminID))
    }

    return resp, nil
}

4. Batch Operations

// Batch insert notification logs
func (ps *PushService) batchInsertLogs(logs []models.PushNotificationLog) error {
    batchSize := 100

    for i := 0; i < len(logs); i += batchSize {
        end := i + batchSize
        if end > len(logs) {
            end = len(logs)
        }

        batch := logs[i:end]

        if err := ps.db.CreateInBatches(batch, batchSize).Error; err != nil {
            return err
        }
    }

    return nil
}

5. Goroutine Pooling

type WorkerPool struct {
    tasks   chan func()
    workers int
}

func NewWorkerPool(workers int) *WorkerPool {
    wp := &WorkerPool{
        tasks:   make(chan func(), 1000),
        workers: workers,
    }

    // Start workers
    for i := 0; i < workers; i++ {
        go wp.worker()
    }

    return wp
}

func (wp *WorkerPool) worker() {
    for task := range wp.tasks {
        task()
    }
}

func (wp *WorkerPool) Submit(task func()) {
    wp.tasks <- task
}

// Usage in PushService
func (ps *PushService) SendToMultipleUsers(userIDs []uuid.UUID, payload types.PushPayload) error {
    pool := NewWorkerPool(50) // 50 concurrent workers

    for _, userID := range userIDs {
        uid := userID // Capture for closure
        pool.Submit(func() {
            ps.SendToUser(uid, payload)
        })
    }

    return nil
}

Code Organization

Project Structure

backend/
├── cmd/
│   └── server/
│       └── main.go                 # Entry point
├── config/
│   ├── database.go                 # DB setup
│   └── vapid.go                    # VAPID config
├── models/
│   ├── push_subscription.go        # GORM models
│   └── push_notification_log.go
├── services/
│   ├── push_service.go             # Core logic
│   └── push_service_test.go        # Unit tests
├── controllers/
│   ├── push_controller.go          # HTTP handlers
│   └── push_controller_test.go
├── routes/
│   └── push_routes.go              # Route definitions
├── middleware/
│   ├── auth.go                     # Authentication
│   ├── rate_limiter.go             # Rate limiting
│   └── cors.go                     # CORS
├── types/
│   └── push_types.go               # Request/response types
├── utils/
│   ├── response.go                 # HTTP helpers
│   ├── device_detector.go          # User agent parsing
│   └── validator.go                # Input validation
├── workers/
│   ├── booking_reminder_worker.go  # Background workers
│   └── notification_scheduler.go
├── metrics/
│   └── push_metrics.go             # Prometheus metrics
├── migrations/
│   └── 001_create_push_tables.sql
├── .env.example
├── .gitignore
├── go.mod
└── README.md

Naming Conventions

// Use clear, descriptive names
✅ func (ps *PushService) SendToUser(userID uuid.UUID, payload types.PushPayload) error
❌ func (ps *PushService) Send(id string, p interface{}) error

// Constants in UPPER_SNAKE_CASE
const (
    MAX_RETRY_ATTEMPTS     = 3
    DEFAULT_BATCH_SIZE     = 100
    WORKER_INTERVAL_MINUTES = 5
)

// Private methods start with lowercase
func (ps *PushService) sendToSubscription(...) error
func (ps *PushService) logSuccess(...) error

// Public methods start with uppercase
func (ps *PushService) SendToUser(...) error
func (ps *PushService) Subscribe(...) error

Testing Strategies

1. Unit Tests

// services/push_service_test.go

func TestPushService_Subscribe(t *testing.T) {
    // Setup test database
    db := setupTestDB(t)
    defer teardownTestDB(db)

    pushService := NewPushService(db)
    userID := uuid.New()

    req := types.SubscribePushRequest{
        Endpoint: "https://fcm.googleapis.com/test-endpoint",
        Keys: types.SubscriptionKeys{
            P256dh: "test-p256dh-key",
            Auth:   "test-auth-key",
        },
        UserAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Chrome/120.0.0.0",
    }

    // Test subscription
    response, err := pushService.Subscribe(&userID, nil, req)

    assert.NoError(t, err)
    assert.True(t, response.Success)
    assert.NotEqual(t, uuid.Nil, response.SubscriptionID)
    assert.Contains(t, response.DeviceName, "Chrome")

    // Verify database
    var subscription models.PushSubscription
    err = db.Where("endpoint = ?", req.Endpoint).First(&subscription).Error
    assert.NoError(t, err)
    assert.Equal(t, userID, *subscription.UserID)
    assert.True(t, subscription.IsActive)
}

2. Integration Tests

func TestPushNotificationFlow(t *testing.T) {
    // Setup test environment
    db := setupTestDB(t)
    defer teardownTestDB(db)

    pushService := NewPushService(db)
    userID := uuid.New()

    // 1. Subscribe
    subResp, err := pushService.Subscribe(&userID, nil, testSubscriptionRequest())
    assert.NoError(t, err)

    // 2. Send notification
    payload := types.PushPayload{
        Title: "Test Notification",
        Body:  "This is a test",
    }
    err = pushService.SendToUser(userID, payload)
    assert.NoError(t, err)

    // 3. Verify log created
    var log models.PushNotificationLog
    err = db.Where("subscription_id = ?", subResp.SubscriptionID).
        First(&log).Error
    assert.NoError(t, err)
    assert.Equal(t, "Test Notification", log.Title)
}

3. End-to-End Tests

// e2e/push-notifications.spec.ts

import { test, expect } from '@playwright/test';

test('push notification subscription flow', async ({ page, context }) => {
  // Grant notification permission
  await context.grantPermissions(['notifications']);

  // Navigate to app
  await page.goto('http://localhost:3000');

  // Wait for service worker registration
  await page.waitForFunction(() => {
    return navigator.serviceWorker.controller !== null;
  });

  // Click subscribe button
  await page.click('[data-testid="subscribe-notifications"]');

  // Wait for subscription success message
  await expect(page.locator('[data-testid="subscription-success"]')).toBeVisible();

  // Verify subscription in backend
  const devices = await page.evaluate(async () => {
    const response = await fetch('/api/push/devices');
    return response.json();
  });

  expect(devices.count).toBeGreaterThan(0);
});

4. Load Testing

// k6-load-test.js

import http from 'k6/http';
import { check, sleep } from 'k6';

export let options = {
  stages: [
    { duration: '1m', target: 50 },   // Ramp up to 50 users
    { duration: '3m', target: 50 },   // Stay at 50 users
    { duration: '1m', target: 100 },  // Ramp up to 100 users
    { duration: '3m', target: 100 },  // Stay at 100 users
    { duration: '1m', target: 0 },    // Ramp down
  ],
  thresholds: {
    http_req_duration: ['p(95)<500'], // 95% of requests under 500ms
    http_req_failed: ['rate<0.01'],   // Less than 1% failure rate
  },
};

export default function () {
  const payload = JSON.stringify({
    endpoint: `https://fcm.googleapis.com/test-${__VU}-${__ITER}`,
    keys: {
      p256dh: 'test-p256dh-key',
      auth: 'test-auth-key',
    },
    userAgent: 'k6-load-test',
  });

  const params = {
    headers: {
      'Content-Type': 'application/json',
      'Cookie': 'auth-token=test-token',
    },
  };

  const res = http.post('http://localhost:8081/api/push/subscribe', payload, params);

  check(res, {
    'status is 200': (r) => r.status === 200,
    'response has subscriptionId': (r) => JSON.parse(r.body).subscriptionId !== undefined,
  });

  sleep(1);
}

Documentation Standards

Code Comments

// PushService handles all push notification operations.
//
// It manages subscriptions, sends notifications via the Web Push Protocol,
// tracks delivery status, and handles automatic retry logic.
//
// Example usage:
//   pushService := NewPushService(db)
//   payload := types.PushPayload{
//       Title: "Booking Confirmed",
//       Body:  "Your booking is confirmed",
//   }
//   err := pushService.SendToUser(userID, payload)
type PushService struct {
    db              *gorm.DB
    vapidPublicKey  string
    vapidPrivateKey string
    vapidSubject    string
}

// SendToUser sends a notification to all active devices of a user.
//
// Parameters:
//   userID - UUID of the user to notify
//   payload - Notification content (title, body, etc.)
//
// Returns:
//   error - nil on success, error if no active subscriptions or send fails
//
// The notification is sent to all active devices in parallel using goroutines.
// Individual device failures do not cause the entire operation to fail.
func (ps *PushService) SendToUser(userID uuid.UUID, payload types.PushPayload) error {
    // Implementation...
}

API Documentation

# openapi.yml

openapi: 3.0.0
info:
  title: Push Notifications API
  version: 1.0.0

paths:
  /api/push/subscribe:
    post:
      summary: Subscribe to push notifications
      description: Creates or updates a push subscription for the authenticated user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - endpoint
                - keys
              properties:
                endpoint:
                  type: string
                  description: Browser push service URL
                  example: "https://fcm.googleapis.com/..."
                keys:
                  type: object
                  required:
                    - p256dh
                    - auth
                  properties:
                    p256dh:
                      type: string
                      description: Public key for encryption
                    auth:
                      type: string
                      description: Authentication secret
                userAgent:
                  type: string
                  description: Browser user agent
      responses:
        '200':
          description: Subscription successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  subscriptionId:
                    type: string
                    format: uuid
                  deviceName:
                    type: string
                    example: "Chrome on macOS"
        '400':
          description: Invalid request
        '401':
          description: Unauthorized

Deployment Checklist

Pre-Deployment

[ ] VAPID keys generated and configured
[ ] Environment variables set for all environments
[ ] Database migrations applied
[ ] All tests passing (unit, integration, E2E)
[ ] Code reviewed and approved
[ ] Security audit completed
[ ] Performance benchmarks met
[ ] Documentation updated

Deployment

[ ] Deploy to staging environment
[ ] Run smoke tests in staging
[ ] Verify service health checks passing
[ ] Check metrics in Grafana
[ ] Deploy to production with rolling update
[ ] Monitor error rates during deployment
[ ] Verify zero downtime

Post-Deployment

[ ] Monitor metrics for 1 hour
[ ] Check error tracking (Sentry)
[ ] Verify push notifications sending successfully
[ ] Test subscription flow end-to-end
[ ] Review logs for anomalies
[ ] Update status page
[ ] Notify stakeholders of deployment

Summary

You now have:

✅ Security best practices (secrets, HTTPS, CORS, CSP)
✅ VAPID key management and rotation
✅ Comprehensive input validation
✅ SQL injection prevention
✅ Authentication & authorization patterns
✅ Performance optimization techniques
✅ Code organization standards
✅ Testing strategies (unit, integration, E2E, load)
✅ Documentation standards
✅ Complete deployment checklist

Next Steps

➡️ Part 8: Complete Reference & FAQ

Part 8 (final) will cover:

Complete API reference
Frequently Asked Questions (FAQ)
Troubleshooting guide
Browser compatibility matrix
Migration guides
Glossary of terms
Additional resources
Community support

# Self-Hosted Push Notifications Part-6

Bipin C — Wed, 22 Oct 2025 12:11:08 +0000

Self-Hosted Push Notifications Specification

Part 6: Monitoring, Debugging & Troubleshooting

Version: 1.0
Last Updated: October 2025
Prerequisites: Part 5: Advanced Features & Production Deployment
Author: Bunty9
License: MIT (Free to use and adapt)

Metrics & Monitoring
Logging Best Practices
Performance Profiling
Health Checks
Error Tracking
Alerting Strategies
Debugging Tools
Common Issues & Solutions
Incident Response
Analytics & Reporting

Metrics & Monitoring

Key Metrics to Track

1. Delivery Metrics

-- Overall delivery rate (last 24 hours)
SELECT
  status,
  COUNT(*) as count,
  ROUND(COUNT(*) * 100.0 / SUM(COUNT(*)) OVER (), 2) as percentage
FROM push_notification_logs
WHERE sent_at > NOW() - INTERVAL '24 hours'
GROUP BY status;

-- Expected result:
-- status  | count | percentage
-- --------+-------+-----------
-- sent    | 8,543 |  95.23
-- failed  |   234 |   2.61
-- expired |   193 |   2.16

Target: >90% success rate

2. Active Subscriptions

-- Active subscriptions by user type
SELECT
  CASE
    WHEN user_id IS NOT NULL THEN 'users'
    WHEN admin_id IS NOT NULL THEN 'admins'
  END as type,
  COUNT(*) as active_subscriptions,
  COUNT(DISTINCT COALESCE(user_id, admin_id)) as unique_accounts,
  ROUND(AVG(failure_count), 2) as avg_failure_count
FROM push_subscriptions
WHERE is_active = TRUE
GROUP BY type;

Target: Failure count < 1.0

3. Device Distribution

-- Browser and OS distribution
SELECT
  browser,
  os,
  device_type,
  COUNT(*) as count
FROM push_subscriptions
WHERE is_active = TRUE
GROUP BY browser, os, device_type
ORDER BY count DESC;

4. Notification Volume

-- Notifications sent per hour (last 24 hours)
SELECT
  DATE_TRUNC('hour', sent_at) as hour,
  COUNT(*) as notifications_sent,
  COUNT(DISTINCT subscription_id) as unique_devices,
  COUNT(*) FILTER (WHERE status = 'sent') as successful,
  COUNT(*) FILTER (WHERE status = 'failed') as failed
FROM push_notification_logs
WHERE sent_at > NOW() - INTERVAL '24 hours'
GROUP BY hour
ORDER BY hour DESC;

Prometheus Metrics

Go Backend Metrics

// metrics/push_metrics.go

package metrics

import (
    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promauto"
)

var (
    // Notification counters
    NotificationsSent = promauto.NewCounterVec(
        prometheus.CounterOpts{
            Name: "push_notifications_sent_total",
            Help: "Total number of push notifications sent",
        },
        []string{"status", "type"},
    )

    NotificationDuration = promauto.NewHistogramVec(
        prometheus.HistogramOpts{
            Name:    "push_notification_duration_seconds",
            Help:    "Duration of push notification sending",
            Buckets: prometheus.DefBuckets,
        },
        []string{"status"},
    )

    // Subscription metrics
    ActiveSubscriptions = promauto.NewGaugeVec(
        prometheus.GaugeOpts{
            Name: "push_subscriptions_active",
            Help: "Number of active push subscriptions",
        },
        []string{"user_type"},
    )

    SubscriptionFailures = promauto.NewCounterVec(
        prometheus.CounterOpts{
            Name: "push_subscription_failures_total",
            Help: "Total number of subscription failures",
        },
        []string{"reason"},
    )

    // Worker metrics
    WorkerRuns = promauto.NewCounterVec(
        prometheus.CounterOpts{
            Name: "push_worker_runs_total",
            Help: "Total number of worker executions",
        },
        []string{"worker", "status"},
    )

    WorkerDuration = promauto.NewHistogramVec(
        prometheus.HistogramOpts{
            Name:    "push_worker_duration_seconds",
            Help:    "Duration of worker execution",
            Buckets: prometheus.DefBuckets,
        },
        []string{"worker"},
    )
)

// Usage in PushService
func (ps *PushService) sendToSubscription(subscription models.PushSubscription, payload types.PushPayload) error {
    start := time.Now()

    err := ps.doSend(subscription, payload)

    status := "success"
    if err != nil {
        status = "error"
    }

    // Record metrics
    NotificationsSent.WithLabelValues(status, payload.Type).Inc()
    NotificationDuration.WithLabelValues(status).Observe(time.Since(start).Seconds())

    return err
}

Prometheus Configuration

# prometheus.yml
global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'user-service'
    static_configs:
      - targets: ['user-service:8081']
    metrics_path: /metrics

  - job_name: 'admin-service'
    static_configs:
      - targets: ['admin-service:8082']
    metrics_path: /metrics

Grafana Dashboards

Push Notifications Dashboard

{
  "dashboard": {
    "title": "Push Notifications Monitoring",
    "panels": [
      {
        "title": "Delivery Rate",
        "type": "graph",
        "targets": [
          {
            "expr": "rate(push_notifications_sent_total{status=\"success\"}[5m])",
            "legendFormat": "Successful"
          },
          {
            "expr": "rate(push_notifications_sent_total{status=\"error\"}[5m])",
            "legendFormat": "Failed"
          }
        ]
      },
      {
        "title": "Active Subscriptions",
        "type": "stat",
        "targets": [
          {
            "expr": "sum(push_subscriptions_active)"
          }
        ]
      },
      {
        "title": "Notification Latency (p50, p95, p99)",
        "type": "graph",
        "targets": [
          {
            "expr": "histogram_quantile(0.50, rate(push_notification_duration_seconds_bucket[5m]))",
            "legendFormat": "p50"
          },
          {
            "expr": "histogram_quantile(0.95, rate(push_notification_duration_seconds_bucket[5m]))",
            "legendFormat": "p95"
          },
          {
            "expr": "histogram_quantile(0.99, rate(push_notification_duration_seconds_bucket[5m]))",
            "legendFormat": "p99"
          }
        ]
      },
      {
        "title": "Worker Execution Duration",
        "type": "graph",
        "targets": [
          {
            "expr": "rate(push_worker_duration_seconds_sum[5m]) / rate(push_worker_duration_seconds_count[5m])",
            "legendFormat": "{{worker}}"
          }
        ]
      }
    ]
  }
}

Logging Best Practices

Structured Logging

// Use structured logging with logrus
import (
    log "github.com/sirupsen/logrus"
)

func init() {
    // Set JSON formatter for production
    log.SetFormatter(&log.JSONFormatter{})

    // Set log level from environment
    level, err := log.ParseLevel(os.Getenv("LOG_LEVEL"))
    if err != nil {
        level = log.InfoLevel
    }
    log.SetLevel(level)
}

// Structured log entries
func (ps *PushService) sendToSubscription(subscription models.PushSubscription, payload types.PushPayload) error {
    log.WithFields(log.Fields{
        "subscription_id": subscription.ID,
        "user_id":        subscription.UserID,
        "device_name":    subscription.DeviceName,
        "notification_type": payload.Type,
    }).Info("Sending push notification")

    err := ps.doSend(subscription, payload)

    if err != nil {
        log.WithFields(log.Fields{
            "subscription_id": subscription.ID,
            "error":          err.Error(),
            "notification_type": payload.Type,
        }).Error("Failed to send push notification")
    } else {
        log.WithFields(log.Fields{
            "subscription_id": subscription.ID,
            "notification_type": payload.Type,
            "duration_ms":    time.Since(start).Milliseconds(),
        }).Info("Push notification sent successfully")
    }

    return err
}

Log Aggregation

Fluentd Configuration:

# fluentd.conf
<source>
  @type tail
  path /var/log/user-service/*.log
  pos_file /var/log/td-agent/user-service.log.pos
  tag user-service
  <parse>
    @type json
    time_key time
    time_format %Y-%m-%dT%H:%M:%S.%NZ
  </parse>
</source>

<filter user-service>
  @type record_transformer
  <record>
    service ${tag}
    environment production
  </record>
</filter>

<match user-service>
  @type elasticsearch
  host elasticsearch
  port 9200
  logstash_format true
  logstash_prefix user-service
  include_tag_key true
  type_name _doc
</match>

Performance Profiling

Go pprof Integration

// Enable pprof endpoints
import (
    _ "net/http/pprof"
)

func main() {
    // Start pprof server on separate port
    go func() {
        log.Println("pprof server listening on :6060")
        log.Println(http.ListenAndServe(":6060", nil))
    }()

    // Start main application...
}

Profiling Commands

# CPU profiling
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

# Memory profiling
go tool pprof http://localhost:6060/debug/pprof/heap

# Goroutine profiling
go tool pprof http://localhost:6060/debug/pprof/goroutine

# View profile in web browser
go tool pprof -http=:8080 profile.pb.gz

Profiling Analysis

// Add custom profiling markers
import "runtime/trace"

func (ps *PushService) SendBatch(subscriptions []models.PushSubscription, payload types.PushPayload) error {
    ctx, task := trace.NewTask(context.Background(), "SendBatch")
    defer task.End()

    trace.Logf(ctx, "info", "Processing %d subscriptions", len(subscriptions))

    // Process batch...

    return nil
}

Health Checks

Comprehensive Health Endpoint

// controllers/health_controller.go

type HealthResponse struct {
    Status     string                 `json:"status"`
    Timestamp  time.Time             `json:"timestamp"`
    Checks     map[string]HealthCheck `json:"checks"`
}

type HealthCheck struct {
    Status  string `json:"status"`
    Message string `json:"message,omitempty"`
}

func (hc *HealthController) CheckHealth(c *gin.Context) {
    response := HealthResponse{
        Timestamp: time.Now(),
        Checks:    make(map[string]HealthCheck),
    }

    // Check database connection
    sqlDB, err := hc.db.DB()
    if err != nil {
        response.Checks["database"] = HealthCheck{
            Status:  "unhealthy",
            Message: err.Error(),
        }
    } else {
        ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
        defer cancel()

        if err := sqlDB.PingContext(ctx); err != nil {
            response.Checks["database"] = HealthCheck{
                Status:  "unhealthy",
                Message: err.Error(),
            }
        } else {
            response.Checks["database"] = HealthCheck{Status: "healthy"}
        }
    }

    // Check VAPID configuration
    if os.Getenv("VAPID_PRIVATE_KEY") == "" || os.Getenv("VAPID_PUBLIC_KEY") == "" {
        response.Checks["vapid"] = HealthCheck{
            Status:  "unhealthy",
            Message: "VAPID keys not configured",
        }
    } else {
        response.Checks["vapid"] = HealthCheck{Status: "healthy"}
    }

    // Check active subscriptions
    var activeCount int64
    hc.db.Model(&models.PushSubscription{}).Where("is_active = ?", true).Count(&activeCount)

    response.Checks["subscriptions"] = HealthCheck{
        Status:  "healthy",
        Message: fmt.Sprintf("%d active subscriptions", activeCount),
    }

    // Check worker status (optional)
    if hc.workerStatus != nil && !hc.workerStatus.IsRunning() {
        response.Checks["worker"] = HealthCheck{
            Status:  "degraded",
            Message: "BookingReminderWorker not running",
        }
    } else {
        response.Checks["worker"] = HealthCheck{Status: "healthy"}
    }

    // Determine overall status
    allHealthy := true
    for _, check := range response.Checks {
        if check.Status != "healthy" {
            allHealthy = false
            break
        }
    }

    if allHealthy {
        response.Status = "healthy"
        c.JSON(http.StatusOK, response)
    } else {
        response.Status = "unhealthy"
        c.JSON(http.StatusServiceUnavailable, response)
    }
}

Kubernetes Liveness & Readiness

apiVersion: v1
kind: Pod
spec:
  containers:
  - name: user-service
    livenessProbe:
      httpGet:
        path: /health
        port: 8081
      initialDelaySeconds: 30
      periodSeconds: 10
      timeoutSeconds: 5
      failureThreshold: 3

    readinessProbe:
      httpGet:
        path: /health
        port: 8081
      initialDelaySeconds: 5
      periodSeconds: 5
      timeoutSeconds: 3
      failureThreshold: 3

Error Tracking

Sentry Integration

// Initialize Sentry
import "github.com/getsentry/sentry-go"

func initSentry() {
    err := sentry.Init(sentry.ClientOptions{
        Dsn: os.Getenv("SENTRY_DSN"),
        Environment: os.Getenv("ENV"),
        Release: "user-service@1.0.0",
    })
    if err != nil {
        log.Fatalf("Sentry init failed: %v", err)
    }
}

// Capture errors
func (ps *PushService) sendToSubscription(subscription models.PushSubscription, payload types.PushPayload) error {
    err := ps.doSend(subscription, payload)

    if err != nil {
        // Report to Sentry
        sentry.WithScope(func(scope *sentry.Scope) {
            scope.SetContext("subscription", map[string]interface{}{
                "id":          subscription.ID,
                "device_name": subscription.DeviceName,
                "browser":     subscription.Browser,
            })
            scope.SetContext("notification", map[string]interface{}{
                "type":  payload.Type,
                "title": payload.Title,
            })
            sentry.CaptureException(err)
        })
    }

    return err
}

Alerting Strategies

Alert Rules

# prometheus-alerts.yml
groups:
  - name: push_notifications
    interval: 30s
    rules:
      # High failure rate
      - alert: PushNotificationFailureRateHigh
        expr: |
          (
            rate(push_notifications_sent_total{status="error"}[5m])
            /
            rate(push_notifications_sent_total[5m])
          ) > 0.10
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Push notification failure rate > 10%"
          description: "{{ $value | humanizePercentage }} of push notifications are failing"

      # No notifications sent
      - alert: PushNotificationsNotSending
        expr: |
          rate(push_notifications_sent_total[10m]) == 0
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "No push notifications sent in last 10 minutes"

      # Subscription count dropping
      - alert: ActiveSubscriptionsDropping
        expr: |
          (
            push_subscriptions_active - push_subscriptions_active offset 1h
          ) < -100
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Active subscriptions dropped by {{ $value }}"

      # Worker not running
      - alert: BookingReminderWorkerDown
        expr: |
          push_worker_runs_total{worker="booking_reminder"} offset 10m
          ==
          push_worker_runs_total{worker="booking_reminder"}
        for: 10m
        labels:
          severity: critical
        annotations:
          summary: "BookingReminderWorker hasn't run in 10 minutes"

      # High latency
      - alert: PushNotificationLatencyHigh
        expr: |
          histogram_quantile(0.95, rate(push_notification_duration_seconds_bucket[5m])) > 5
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Push notification p95 latency > 5s"

Alertmanager Configuration

# alertmanager.yml
global:
  resolve_timeout: 5m

route:
  group_by: ['alertname', 'severity']
  group_wait: 10s
  group_interval: 10s
  repeat_interval: 1h
  receiver: 'default'

  routes:
    - match:
        severity: critical
      receiver: 'pagerduty'
      continue: true

    - match:
        severity: warning
      receiver: 'slack'

receivers:
  - name: 'default'
    email_configs:
      - to: 'alerts@yourdomain.com'

  - name: 'slack'
    slack_configs:
      - api_url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL'
        channel: '#alerts'
        title: '{{ .GroupLabels.alertname }}'
        text: '{{ range .Alerts }}{{ .Annotations.description }}{{ end }}'

  - name: 'pagerduty'
    pagerduty_configs:
      - service_key: 'YOUR_PAGERDUTY_KEY'

Debugging Tools

Database Query Debugging

-- Find subscriptions with high failure counts
SELECT
  id,
  COALESCE(user_id::TEXT, admin_id::TEXT) as owner_id,
  device_name,
  browser,
  failure_count,
  last_used_at,
  created_at
FROM push_subscriptions
WHERE failure_count >= 2
ORDER BY failure_count DESC, last_used_at DESC
LIMIT 20;

-- Check recent failed notifications
SELECT
  pnl.id,
  pnl.title,
  pnl.status,
  pnl.error_message,
  pnl.http_status_code,
  pnl.sent_at,
  ps.device_name,
  ps.browser
FROM push_notification_logs pnl
LEFT JOIN push_subscriptions ps ON pnl.subscription_id = ps.id
WHERE pnl.status = 'failed'
  AND pnl.sent_at > NOW() - INTERVAL '1 hour'
ORDER BY pnl.sent_at DESC
LIMIT 50;

-- Analyze notification volume by hour
SELECT
  DATE_TRUNC('hour', sent_at) as hour,
  COUNT(*) as total,
  COUNT(*) FILTER (WHERE status = 'sent') as sent,
  COUNT(*) FILTER (WHERE status = 'failed') as failed,
  ROUND(COUNT(*) FILTER (WHERE status = 'sent')::NUMERIC * 100 / COUNT(*), 2) as success_rate
FROM push_notification_logs
WHERE sent_at > NOW() - INTERVAL '24 hours'
GROUP BY hour
ORDER BY hour DESC;

Frontend Debugging

// Enable verbose logging
localStorage.setItem('debug_push_notifications', 'true');

// Check subscription status
navigator.serviceWorker.ready.then(async reg => {
  const subscription = await reg.pushManager.getSubscription();
  console.log('Current subscription:', subscription);

  if (subscription) {
    console.log('Endpoint:', subscription.endpoint);
    console.log('Keys:', {
      p256dh: subscription.toJSON().keys.p256dh,
      auth: subscription.toJSON().keys.auth
    });
  }
});

// Monitor service worker messages
navigator.serviceWorker.addEventListener('message', event => {
  console.log('[SW Message]', event.data);
});

// Test push notification
async function testPushNotification() {
  const registration = await navigator.serviceWorker.ready;
  await registration.showNotification('Test Notification', {
    body: 'This is a test',
    icon: '/icon-192x192.png',
    data: { url: '/' }
  });
}

Common Issues & Solutions

Issue 1: Notifications Not Received

Symptoms:

Backend logs show "sent" status
User doesn't receive notification

Debugging:

# Check browser notification permission
# Browser Console:
Notification.permission

# Check service worker status
navigator.serviceWorker.ready.then(reg => console.log(reg.active));

# Check subscription exists in backend
curl -X GET http://localhost:8081/api/push/devices \
  -H "Cookie: auth-token=YOUR_TOKEN"

Solutions:

Permission denied: User must grant permission in browser settings
Service worker not registered: Ensure sw.js exists at /public/sw.js
Subscription expired: User needs to resubscribe

Issue 2: High Failure Rate

Symptoms:

>10% of notifications failing
failure_count increasing for subscriptions

Debugging:

-- Check error messages
SELECT
  error_message,
  http_status_code,
  COUNT(*) as occurrences
FROM push_notification_logs
WHERE status = 'failed'
  AND sent_at > NOW() - INTERVAL '24 hours'
GROUP BY error_message, http_status_code
ORDER BY occurrences DESC;

Common Causes & Solutions:

HTTP Status	Cause	Solution
410 Gone	Subscription expired	Deactivate subscription (auto-handled)
403 Forbidden	Invalid VAPID keys	Verify VAPID configuration
400 Bad Request	Malformed payload	Check payload format
429 Too Many Requests	Rate limit hit	Implement backoff
500 Server Error	Push service issue	Retry with exponential backoff

Issue 3: Worker Not Running

Symptoms:

Reminder notifications not sent
Worker metrics flat

Debugging:

# Check service logs
kubectl logs -f deployment/user-service | grep WorkerGoroutine

# Expected:
# [BookingReminderWorker] Started successfully
# [BookingReminderWorker] Processing 3 bookings

# Check if multiple instances are running
kubectl get pods -l app=user-service

Solutions:

Restart service: kubectl rollout restart deployment/user-service
Check leader election: Ensure only one worker instance has leadership
Verify database connection: Worker requires database access

Issue 4: Memory Leak

Symptoms:

Memory usage increasing over time
OOM kills in Kubernetes

Debugging:

# Memory profiling
go tool pprof http://localhost:6060/debug/pprof/heap

# Check goroutine leaks
go tool pprof http://localhost:6060/debug/pprof/goroutine

# Kubernetes memory usage
kubectl top pod -l app=user-service

Common Causes:

Goroutine leaks: Not closing database connections
Unbounded caches: No cache eviction policy
Large payloads: Storing too much in memory

Solutions:

// Use context with timeout
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

// Close database connections
defer db.Close()

// Use bounded channels
queue := make(chan *PushNotification, 1000)

Incident Response

Incident Response Playbook

1. Detection

Alert fires in Prometheus/Alertmanager
User reports issue
Monitoring dashboard shows anomaly

2. Assessment

# Check service health
curl http://api.yourdomain.com/health

# Check recent errors
kubectl logs -f deployment/user-service --tail=100 | grep ERROR

# Check metrics
# Visit Grafana dashboard: http://grafana.yourdomain.com/d/push-notifications

3. Mitigation

High Failure Rate:

# Check VAPID keys
kubectl get secret vapid-keys -o jsonpath='{.data.public-key}' | base64 -d

# Restart services
kubectl rollout restart deployment/user-service
kubectl rollout restart deployment/admin-service

Database Connection Issues:

# Check database health
kubectl exec -it deployment/postgres -- psql -U push_service -c "SELECT 1;"

# Scale down workers temporarily
kubectl scale deployment/user-service --replicas=1

High Latency:

# Check active goroutines
curl http://localhost:6060/debug/pprof/goroutine?debug=1

# Scale up if needed
kubectl scale deployment/user-service --replicas=5

4. Communication

Update status page
Notify stakeholders
Document in incident log

5. Resolution

Apply fix
Verify metrics returned to normal
Write postmortem

Analytics & Reporting

Weekly Report Query

-- Weekly push notification report
WITH weekly_stats AS (
  SELECT
    DATE_TRUNC('week', sent_at) as week,
    COUNT(*) as total_sent,
    COUNT(*) FILTER (WHERE status = 'sent') as successful,
    COUNT(*) FILTER (WHERE status = 'failed') as failed,
    COUNT(DISTINCT subscription_id) as unique_devices,
    COUNT(DISTINCT COALESCE(user_id, admin_id)) as unique_users
  FROM push_notification_logs
  WHERE sent_at > NOW() - INTERVAL '4 weeks'
  GROUP BY week
)
SELECT
  week,
  total_sent,
  successful,
  failed,
  ROUND(successful::NUMERIC * 100 / total_sent, 2) as success_rate,
  unique_devices,
  unique_users
FROM weekly_stats
ORDER BY week DESC;

Export to CSV

# Export last 7 days of notification data
psql -h localhost -U postgres -d ohhspaces_prod -c "
COPY (
  SELECT
    pnl.sent_at,
    pnl.title,
    pnl.status,
    ps.device_name,
    ps.browser,
    ps.os
  FROM push_notification_logs pnl
  LEFT JOIN push_subscriptions ps ON pnl.subscription_id = ps.id
  WHERE pnl.sent_at > NOW() - INTERVAL '7 days'
  ORDER BY pnl.sent_at DESC
) TO STDOUT WITH CSV HEADER" > push_notifications_export.csv

Summary

You now have:

✅ Comprehensive metrics and monitoring
✅ Structured logging with aggregation
✅ Performance profiling tools
✅ Health check endpoints
✅ Error tracking integration
✅ Alerting rules and strategies
✅ Debugging tools and techniques
✅ Common issues with solutions
✅ Incident response playbook
✅ Analytics and reporting queries

Next Steps

➡️ Part 7: Best Practices, Security & Optimization

Part 7 will cover:

Security best practices
VAPID key management
Input validation
SQL injection prevention
Performance optimization
Code organization
Testing strategies
Documentation standards

# Self-Hosted Push Notifications Part-5

Bipin C — Wed, 22 Oct 2025 12:09:19 +0000

Self-Hosted Push Notifications Specification

Part 5: Advanced Features & Production Deployment

Version: 1.0
Last Updated: October 2025
Prerequisites: Part 4: Service Worker & PWA Configuration
Author: Bunty9
License: MIT (Free to use and adapt)

Advanced Targeting Strategies
Notification Scheduling
Rate Limiting & Throttling
Batch Processing
Priority Queuing
Retry Strategies
Production Deployment
Docker Configuration
Kubernetes Deployment
Load Balancing
Horizontal Scaling
Database Optimization

Advanced Targeting Strategies

Multi-User Targeting

Use Case: Send notification to booking owner + all assigned users.

// services/push_service.go

// SendToMultipleUsers sends notifications to multiple users in parallel
func (ps *PushService) SendToMultipleUsers(userIDs []uuid.UUID, payload types.PushPayload) error {
    if len(userIDs) == 0 {
        return nil
    }

    log.Printf("[PushService] Sending to %d users", len(userIDs))

    // Send to all users in parallel
    for _, userID := range userIDs {
        go func(uid uuid.UUID) {
            if err := ps.SendToUser(uid, payload); err != nil {
                log.Printf("[PushService] Failed to send to user %s: %v", uid, err)
            }
        }(userID)
    }

    return nil
}

// Example: Notify booking owner + assigned users
func (bs *BookingService) NotifyAllBookingParticipants(booking *models.Booking, payload types.PushPayload) error {
    // Collect all user IDs
    userIDs := []uuid.UUID{booking.UserID}

    // Add assigned users
    var seatAssignments []models.SeatAssignment
    bs.db.Where("booking_id = ?", booking.ID).Find(&seatAssignments)

    for _, sa := range seatAssignments {
        if sa.AssignedUserID != nil && *sa.AssignedUserID != booking.UserID {
            userIDs = append(userIDs, *sa.AssignedUserID)
        }
    }

    // Remove duplicates
    userIDs = uniqueUUIDs(userIDs)

    // Send to all
    return bs.pushService.SendToMultipleUsers(userIDs, payload)
}

Role-Based Targeting

Use Case: Send to all admins with specific role (e.g., caretakers).

// SendToAdminRole sends to all admins with a specific role
func (ps *PushService) SendToAdminRole(role string, payload types.PushPayload) error {
    var adminIDs []uuid.UUID

    // Query admins by role
    err := ps.db.Table("admins").
        Where("role = ? AND is_active = ?", role, true).
        Pluck("id", &adminIDs).Error

    if err != nil {
        return fmt.Errorf("failed to fetch admins: %w", err)
    }

    if len(adminIDs) == 0 {
        log.Printf("[PushService] No admins found with role: %s", role)
        return nil
    }

    log.Printf("[PushService] Sending to %d %s admins", len(adminIDs), role)

    // Send to all admins
    for _, adminID := range adminIDs {
        go ps.SendToAdmin(adminID, payload)
    }

    return nil
}

Caretaker Targeting by Space

Use Case: Notify caretakers assigned to a specific space.

// SendToCaretakersOfSpace sends to caretakers assigned to a space
func (ps *PushService) SendToCaretakersOfSpace(spaceID uuid.UUID, payload types.PushPayload) error {
    var space models.Space
    err := ps.db.First(&space, spaceID).Error
    if err != nil {
        return fmt.Errorf("space not found: %w", err)
    }

    if len(space.CaretakerIDs) == 0 {
        log.Printf("[PushService] No caretakers assigned to space: %s", space.Name)
        return nil
    }

    log.Printf("[PushService] Sending to %d caretakers for space: %s",
        len(space.CaretakerIDs), space.Name)

    // Send to all caretakers
    for _, caretakerIDStr := range space.CaretakerIDs {
        caretakerID, err := uuid.Parse(caretakerIDStr)
        if err != nil {
            log.Printf("[PushService] Invalid caretaker ID: %s", caretakerIDStr)
            continue
        }

        go ps.SendToAdmin(caretakerID, payload)
    }

    return nil
}

Conditional Targeting

Use Case: Send only to users matching specific criteria.

// SendToUsersWithCondition sends to users matching a condition
func (ps *PushService) SendToUsersWithCondition(
    condition string,
    args []interface{},
    payload types.PushPayload,
) error {
    var subscriptions []models.PushSubscription

    // Query subscriptions with custom condition
    query := ps.db.Where("is_active = ? AND user_id IS NOT NULL", true)
    if condition != "" {
        query = query.Where(condition, args...)
    }

    err := query.Find(&subscriptions).Error
    if err != nil {
        return fmt.Errorf("failed to query subscriptions: %w", err)
    }

    log.Printf("[PushService] Sending to %d users matching condition", len(subscriptions))

    // Send to all matching subscriptions
    for _, subscription := range subscriptions {
        go ps.sendToSubscription(subscription, payload)
    }

    return nil
}

// Example: Notify users with bookings starting in next 24 hours
func (bs *BookingService) NotifyUpcomingBookings() error {
    payload := types.PushPayload{
        Title: "Booking Starting Soon",
        Body:  "Your booking starts within 24 hours",
        Type:  "booking_reminder_24h",
        URL:   "/bookings",
    }

    condition := `user_id IN (
        SELECT user_id FROM bookings
        WHERE start_time BETWEEN NOW() AND NOW() + INTERVAL '24 hours'
        AND status = 'confirmed'
    )`

    return bs.pushService.SendToUsersWithCondition(condition, []interface{}{}, payload)
}

Notification Scheduling

Background Worker Implementation

File: workers/notification_scheduler.go

package workers

import (
    "log"
    "time"

    "gorm.io/gorm"
    "your-app/models"
    "your-app/services"
    "your-app/types"
)

// NotificationScheduler handles scheduled notifications
type NotificationScheduler struct {
    db          *gorm.DB
    pushService *services.PushService
    ticker      *time.Ticker
    done        chan bool
}

// NewNotificationScheduler creates a new scheduler
func NewNotificationScheduler(db *gorm.DB, pushService *services.PushService) *NotificationScheduler {
    return &NotificationScheduler{
        db:          db,
        pushService: pushService,
        done:        make(chan bool),
    }
}

// Start begins the scheduler
func (ns *NotificationScheduler) Start() {
    ns.ticker = time.NewTicker(1 * time.Minute)

    go func() {
        log.Println("[NotificationScheduler] Started")

        for {
            select {
            case <-ns.ticker.C:
                ns.processScheduledNotifications()
            case <-ns.done:
                log.Println("[NotificationScheduler] Stopped")
                return
            }
        }
    }()
}

// Stop halts the scheduler
func (ns *NotificationScheduler) Stop() {
    ns.ticker.Stop()
    ns.done <- true
}

// processScheduledNotifications sends due notifications
func (ns *NotificationScheduler) processScheduledNotifications() {
    var scheduledNotifications []models.ScheduledNotification

    // Find notifications due now
    err := ns.db.Where("scheduled_at <= ? AND status = ?", time.Now(), "pending").
        Find(&scheduledNotifications).Error

    if err != nil {
        log.Printf("[NotificationScheduler] Error fetching scheduled notifications: %v", err)
        return
    }

    if len(scheduledNotifications) == 0 {
        return
    }

    log.Printf("[NotificationScheduler] Processing %d scheduled notifications", len(scheduledNotifications))

    for _, sn := range scheduledNotifications {
        go ns.sendScheduledNotification(sn)
    }
}

// sendScheduledNotification sends a single scheduled notification
func (ns *NotificationScheduler) sendScheduledNotification(sn models.ScheduledNotification) {
    payload := types.PushPayload{
        Title: sn.Title,
        Body:  sn.Body,
        Icon:  sn.Icon,
        URL:   sn.URL,
        Data:  sn.Data,
    }

    var err error

    // Send based on recipient type
    switch sn.RecipientType {
    case "user":
        err = ns.pushService.SendToUser(sn.RecipientID, payload)
    case "admin":
        err = ns.pushService.SendToAdmin(sn.RecipientID, payload)
    case "broadcast":
        err = ns.pushService.SendBroadcastToAllUsers(payload)
    default:
        log.Printf("[NotificationScheduler] Unknown recipient type: %s", sn.RecipientType)
        return
    }

    // Update status
    if err != nil {
        ns.db.Model(&sn).Updates(map[string]interface{}{
            "status":       "failed",
            "error":        err.Error(),
            "processed_at": time.Now(),
        })
    } else {
        ns.db.Model(&sn).Updates(map[string]interface{}{
            "status":       "sent",
            "processed_at": time.Now(),
        })
    }
}

Scheduled Notification Model

// models/scheduled_notification.go

type ScheduledNotification struct {
    ID            uuid.UUID `gorm:"type:uuid;primary_key"`
    RecipientType string    `gorm:"type:varchar(20)"` // user, admin, broadcast
    RecipientID   uuid.UUID `gorm:"type:uuid"`
    Title         string    `gorm:"type:varchar(255)"`
    Body          string    `gorm:"type:text"`
    Icon          string    `gorm:"type:varchar(255)"`
    URL           string    `gorm:"type:varchar(255)"`
    Data          datatypes.JSON `gorm:"type:jsonb"`
    ScheduledAt   time.Time `gorm:"not null;index"`
    Status        string    `gorm:"type:varchar(20);default:'pending'"` // pending, sent, failed
    Error         string    `gorm:"type:text"`
    ProcessedAt   *time.Time
    CreatedAt     time.Time
}

Scheduling API

// controllers/notification_controller.go

// ScheduleNotification handles POST /api/notifications/schedule
func (nc *NotificationController) ScheduleNotification(c *gin.Context) {
    var req types.ScheduleNotificationRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        utils.ErrorResponse(c, http.StatusBadRequest, "Invalid request")
        return
    }

    scheduledNotification := models.ScheduledNotification{
        RecipientType: req.RecipientType,
        RecipientID:   req.RecipientID,
        Title:         req.Title,
        Body:          req.Body,
        Icon:          req.Icon,
        URL:           req.URL,
        Data:          req.Data,
        ScheduledAt:   req.ScheduledAt,
        Status:        "pending",
    }

    if err := nc.db.Create(&scheduledNotification).Error; err != nil {
        utils.ErrorResponse(c, http.StatusInternalServerError, "Failed to schedule notification")
        return
    }

    utils.SuccessResponse(c, "Notification scheduled successfully", scheduledNotification)
}

Rate Limiting & Throttling

Per-User Rate Limiting

// middleware/rate_limiter.go

import (
    "net/http"
    "sync"
    "time"

    "github.com/gin-gonic/gin"
    "golang.org/x/time/rate"
)

type RateLimiter struct {
    limiters map[string]*rate.Limiter
    mu       sync.RWMutex
    limit    rate.Limit
    burst    int
}

func NewRateLimiter(requestsPerMinute int, burst int) *RateLimiter {
    return &RateLimiter{
        limiters: make(map[string]*rate.Limiter),
        limit:    rate.Limit(requestsPerMinute) / 60, // Per second
        burst:    burst,
    }
}

func (rl *RateLimiter) getLimiter(key string) *rate.Limiter {
    rl.mu.RLock()
    limiter, exists := rl.limiters[key]
    rl.mu.RUnlock()

    if !exists {
        rl.mu.Lock()
        limiter = rate.NewLimiter(rl.limit, rl.burst)
        rl.limiters[key] = limiter
        rl.mu.Unlock()
    }

    return limiter
}

func (rl *RateLimiter) Middleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        userID, exists := c.Get("userID")
        if !exists {
            c.JSON(http.StatusUnauthorized, gin.H{"error": "Unauthorized"})
            c.Abort()
            return
        }

        key := userID.(string)
        limiter := rl.getLimiter(key)

        if !limiter.Allow() {
            c.JSON(http.StatusTooManyRequests, gin.H{
                "error": "Rate limit exceeded. Try again later.",
            })
            c.Abort()
            return
        }

        c.Next()
    }
}

// Usage in routes
func SetupPushRoutes(router *gin.Engine, pushController *controllers.PushController) {
    rateLimiter := NewRateLimiter(10, 5) // 10 requests/min, burst 5

    push := router.Group("/api/push")
    push.Use(middleware.AuthMiddleware())
    push.Use(rateLimiter.Middleware())
    {
        push.POST("/subscribe", pushController.Subscribe)
        push.POST("/unsubscribe", pushController.Unsubscribe)
    }
}

Global Rate Limiting

// Limit total push notifications sent per second
type GlobalRateLimiter struct {
    limiter *rate.Limiter
}

func NewGlobalRateLimiter(notificationsPerSecond int) *GlobalRateLimiter {
    return &GlobalRateLimiter{
        limiter: rate.NewLimiter(rate.Limit(notificationsPerSecond), notificationsPerSecond*2),
    }
}

func (grl *GlobalRateLimiter) Wait(ctx context.Context) error {
    return grl.limiter.Wait(ctx)
}

// In PushService
func (ps *PushService) sendToSubscription(subscription models.PushSubscription, payload types.PushPayload) error {
    // Wait for rate limit token
    if ps.globalRateLimiter != nil {
        ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
        defer cancel()

        if err := ps.globalRateLimiter.Wait(ctx); err != nil {
            return fmt.Errorf("rate limit wait failed: %w", err)
        }
    }

    // Send notification...
}

Batch Processing

Batch Send Implementation

// SendBatch sends notifications in controlled batches
func (ps *PushService) SendBatch(subscriptions []models.PushSubscription, payload types.PushPayload) error {
    batchSize := 100
    delayBetweenBatches := 100 * time.Millisecond

    log.Printf("[PushService] Sending to %d subscriptions in batches of %d", len(subscriptions), batchSize)

    for i := 0; i < len(subscriptions); i += batchSize {
        end := i + batchSize
        if end > len(subscriptions) {
            end = len(subscriptions)
        }

        batch := subscriptions[i:end]

        // Send batch in parallel
        var wg sync.WaitGroup
        for _, subscription := range batch {
            wg.Add(1)
            go func(sub models.PushSubscription) {
                defer wg.Done()
                ps.sendToSubscription(sub, payload)
            }(subscription)
        }

        wg.Wait()

        // Delay between batches to avoid overwhelming the system
        if end < len(subscriptions) {
            time.Sleep(delayBetweenBatches)
        }

        log.Printf("[PushService] Processed batch %d-%d of %d", i+1, end, len(subscriptions))
    }

    return nil
}

Priority Queuing

Priority Queue Implementation

// types/priority_queue.go

type PriorityNotification struct {
    Priority int // 0 = highest, 10 = lowest
    Subscription models.PushSubscription
    Payload types.PushPayload
}

type PriorityQueue []*PriorityNotification

func (pq PriorityQueue) Len() int { return len(pq) }

func (pq PriorityQueue) Less(i, j int) bool {
    return pq[i].Priority < pq[j].Priority
}

func (pq PriorityQueue) Swap(i, j int) {
    pq[i], pq[j] = pq[j], pq[i]
}

func (pq *PriorityQueue) Push(x interface{}) {
    *pq = append(*pq, x.(*PriorityNotification))
}

func (pq *PriorityQueue) Pop() interface{} {
    old := *pq
    n := len(old)
    item := old[n-1]
    *pq = old[0 : n-1]
    return item
}

// Worker that processes priority queue
func (ps *PushService) StartPriorityWorker() {
    pq := make(PriorityQueue, 0)
    heap.Init(&pq)

    for {
        if pq.Len() > 0 {
            notif := heap.Pop(&pq).(*PriorityNotification)
            ps.sendToSubscription(notif.Subscription, notif.Payload)
        } else {
            time.Sleep(100 * time.Millisecond)
        }
    }
}

Retry Strategies

Exponential Backoff

// sendWithRetry sends notification with exponential backoff
func (ps *PushService) sendWithRetry(
    subscription models.PushSubscription,
    payload types.PushPayload,
    maxRetries int,
) error {
    var lastErr error

    for attempt := 0; attempt <= maxRetries; attempt++ {
        err := ps.sendToSubscription(subscription, payload)

        if err == nil {
            return nil // Success
        }

        lastErr = err

        // Don't retry on certain errors
        if isNonRetryableError(err) {
            return err
        }

        if attempt < maxRetries {
            // Exponential backoff: 1s, 2s, 4s, 8s, ...
            backoff := time.Duration(1<<uint(attempt)) * time.Second
            log.Printf("[PushService] Retry %d/%d after %v for subscription %s",
                attempt+1, maxRetries, backoff, subscription.ID)
            time.Sleep(backoff)
        }
    }

    return fmt.Errorf("failed after %d retries: %w", maxRetries, lastErr)
}

func isNonRetryableError(err error) bool {
    // 410 Gone, 403 Forbidden = subscription expired/invalid
    return strings.Contains(err.Error(), "410") ||
           strings.Contains(err.Error(), "403")
}

Production Deployment

Environment Configuration

Production .env.prod:

# Server
PORT=8081
ENV=production

# Database
DB_HOST=prod-postgres.internal
DB_PORT=5432
DB_USER=push_service
DB_PASSWORD=${DATABASE_PASSWORD}  # From secrets
DB_NAME=ohhspaces_prod
DB_SSLMODE=require
DB_MAX_OPEN_CONNS=100
DB_MAX_IDLE_CONNS=10

# VAPID (from secrets)
VAPID_PUBLIC_KEY=${VAPID_PUBLIC_KEY}
VAPID_PRIVATE_KEY=${VAPID_PRIVATE_KEY}
VAPID_SUBJECT=mailto:admin@yourdomain.com

# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=1m

# Logging
LOG_LEVEL=info
LOG_FORMAT=json

# Workers
ENABLE_REMINDER_WORKER=true
REMINDER_WORKER_INTERVAL=5m

ENABLE_SCHEDULER_WORKER=true
SCHEDULER_WORKER_INTERVAL=1m

# Performance
MAX_GOROUTINES=1000
BATCH_SIZE=100
BATCH_DELAY_MS=100

Docker Configuration

Dockerfile

# Build stage
FROM golang:1.21-alpine AS builder

WORKDIR /app

# Copy go mod files
COPY go.mod go.sum ./
RUN go mod download

# Copy source code
COPY . .

# Build
RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o user-service ./user-service

# Production stage
FROM alpine:latest

RUN apk --no-cache add ca-certificates

WORKDIR /root/

# Copy binary from builder
COPY --from=builder /app/user-service .

# Copy migrations (optional)
COPY --from=builder /app/migrations ./migrations

EXPOSE 8081

CMD ["./user-service"]

docker-compose.yml

version: '3.8'

services:
  postgres:
    image: postgres:14-alpine
    environment:
      POSTGRES_DB: ohhspaces_prod
      POSTGRES_USER: push_service
      POSTGRES_PASSWORD: ${DATABASE_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U push_service"]
      interval: 10s
      timeout: 5s
      retries: 5

  user-service:
    build:
      context: .
      dockerfile: Dockerfile
    environment:
      DB_HOST: postgres
      DB_PORT: 5432
      DB_USER: push_service
      DB_PASSWORD: ${DATABASE_PASSWORD}
      DB_NAME: ohhspaces_prod
      VAPID_PUBLIC_KEY: ${VAPID_PUBLIC_KEY}
      VAPID_PRIVATE_KEY: ${VAPID_PRIVATE_KEY}
      VAPID_SUBJECT: mailto:admin@yourdomain.com
    ports:
      - "8081:8081"
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

volumes:
  postgres_data:

Kubernetes Deployment

Deployment YAML

File: k8s/user-service-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: user-service
  namespace: production
spec:
  replicas: 3
  selector:
    matchLabels:
      app: user-service
  template:
    metadata:
      labels:
        app: user-service
    spec:
      containers:
      - name: user-service
        image: gcr.io/your-project/user-service:latest
        ports:
        - containerPort: 8081
        env:
        - name: PORT
          value: "8081"
        - name: ENV
          value: "production"
        - name: DB_HOST
          value: "postgres-service"
        - name: DB_PORT
          value: "5432"
        - name: DB_USER
          valueFrom:
            secretKeyRef:
              name: db-credentials
              key: username
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: db-credentials
              key: password
        - name: DB_NAME
          value: "ohhspaces_prod"
        - name: VAPID_PUBLIC_KEY
          valueFrom:
            secretKeyRef:
              name: vapid-keys
              key: public-key
        - name: VAPID_PRIVATE_KEY
          valueFrom:
            secretKeyRef:
              name: vapid-keys
              key: private-key
        - name: VAPID_SUBJECT
          value: "mailto:admin@yourdomain.com"
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8081
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8081
          initialDelaySeconds: 5
          periodSeconds: 5

---
apiVersion: v1
kind: Service
metadata:
  name: user-service
  namespace: production
spec:
  selector:
    app: user-service
  ports:
  - protocol: TCP
    port: 8081
    targetPort: 8081
  type: ClusterIP

Secrets Configuration

# Create database credentials secret
kubectl create secret generic db-credentials \
  --from-literal=username=push_service \
  --from-literal=password='your-secure-password' \
  --namespace=production

# Create VAPID keys secret
kubectl create secret generic vapid-keys \
  --from-literal=public-key='BOzzMgOMwVyuziwHiI8...' \
  --from-literal=private-key='BNw7fc1ayj3-Az-OJ8...' \
  --namespace=production

Load Balancing

Nginx Configuration

upstream user_service {
    least_conn;
    server user-service-1:8081 max_fails=3 fail_timeout=30s;
    server user-service-2:8081 max_fails=3 fail_timeout=30s;
    server user-service-3:8081 max_fails=3 fail_timeout=30s;
}

server {
    listen 443 ssl http2;
    server_name api.yourdomain.com;

    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;

    location /api/push/ {
        proxy_pass http://user_service;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;

        # Timeouts
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}

Horizontal Scaling

Scaling Considerations

Stateless Services: Ensure push service is stateless
Database Connection Pooling: Use connection pool to avoid exhaustion
Worker Coordination: Only one worker instance should run per task type

Worker Leader Election

// Use distributed locking for worker coordination
func (rw *ReminderWorker) Start() {
    // Acquire distributed lock (e.g., Redis, etcd)
    lockKey := "worker:booking_reminder:leader"

    for {
        acquired := acquireLock(lockKey, 60*time.Second)

        if acquired {
            log.Println("[ReminderWorker] Acquired leadership")
            rw.run()
        } else {
            log.Println("[ReminderWorker] Waiting for leadership")
            time.Sleep(30 * time.Second)
        }
    }
}

Database Optimization

Connection Pooling

func setupDatabase(dsn string) (*gorm.DB, error) {
    db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{
        PrepareStmt: true, // Cache prepared statements
    })
    if err != nil {
        return nil, err
    }

    sqlDB, err := db.DB()
    if err != nil {
        return nil, err
    }

    // Connection pool settings
    sqlDB.SetMaxOpenConns(100)      // Max open connections
    sqlDB.SetMaxIdleConns(10)       // Max idle connections
    sqlDB.SetConnMaxLifetime(time.Hour) // Max connection lifetime

    return db, nil
}

Query Optimization

-- Add composite index for common queries
CREATE INDEX idx_push_subscriptions_user_active_last_used
ON push_subscriptions(user_id, is_active, last_used_at DESC)
WHERE is_active = TRUE;

-- Index for notification logs
CREATE INDEX idx_push_notification_logs_user_sent_status
ON push_notification_logs(user_id, sent_at DESC, status);

-- Partial index for active subscriptions
CREATE INDEX idx_active_subscriptions
ON push_subscriptions(user_id, endpoint)
WHERE is_active = TRUE;

Summary

You now have:

✅ Advanced targeting strategies (multi-user, role-based, conditional)
✅ Notification scheduling with background workers
✅ Rate limiting and throttling mechanisms
✅ Batch processing for large-scale sends
✅ Priority queuing for critical notifications
✅ Retry strategies with exponential backoff
✅ Docker containerization
✅ Kubernetes production deployment
✅ Load balancing configuration
✅ Horizontal scaling patterns
✅ Database optimization techniques

Next Steps

➡️ Part 6: Monitoring, Debugging & Troubleshooting

Part 6 will cover:

Metrics and monitoring
Logging best practices
Debugging techniques
Performance profiling
Error tracking
Alerting strategies
Health checks
Incident response

# Self-Hosted Push Notifications Part-4

Bipin C — Wed, 22 Oct 2025 12:06:36 +0000

Self-Hosted Push Notifications Specification

Part 4: Service Worker & PWA Configuration

Version: 1.0
Last Updated: October 2025
Prerequisites: Part 3: Frontend Implementation
Author: Bunty9
License: MIT (Free to use and adapt)

Service Worker Fundamentals
Complete Service Worker Implementation
PWA Manifest Configuration
Notification Customization
Action Handlers
Background Sync
Offline Support
Testing Service Workers
Debugging Tools
Common Pitfalls

Service Worker Fundamentals

What is a Service Worker?

A service worker is a JavaScript file that runs in the background, separate from your web page. It enables features like:

Push Notifications - Receive notifications when app is closed
Offline Support - Cache resources for offline access
Background Sync - Sync data when connection is restored
Intercept Network Requests - Cache strategies, offline fallbacks

Service Worker Lifecycle

┌──────────────┐
│   INSTALL    │  Triggered when SW file changes
└──────┬───────┘
       │
       ▼
┌──────────────┐
│   ACTIVATE   │  Clean up old caches
└──────┬───────┘
       │
       ▼
┌──────────────┐
│     IDLE     │  Waiting for events
└──────┬───────┘
       │
       ▼
┌──────────────┐
│   FETCH /    │  Handle events as they occur
│   PUSH  /    │
│   SYNC       │
└──────┬───────┘
       │
       └─────────> Back to IDLE or TERMINATE

Browser Compatibility

Browser	Service Worker	Push API	Notification API
Chrome	✅ 40+	✅ 42+	✅ 42+
Firefox	✅ 44+	✅ 44+	✅ 44+
Safari	✅ 11.1+	✅ 16+ (macOS only)	⚠️ Limited on iOS
Edge	✅ 17+	✅ 17+	✅ 17+

Important: iOS Safari requires the PWA to be installed to home screen for push notifications to work.

Complete Service Worker Implementation

public/sw.js

This is a production-ready service worker with enhanced notification handling.

// ==================== SERVICE WORKER VERSION ====================
const CACHE_VERSION = 'v1.0.0';
const CACHE_NAME = `ohhspaces-cache-${CACHE_VERSION}`;

// ==================== PUSH EVENT HANDLER ====================

self.addEventListener('push', function (event) {
  console.log('[Service Worker] Push event received');

  if (event.data) {
    try {
      const data = event.data.json();
      console.log('[Service Worker] Push data:', data);

      // Extract notification type
      const notificationType = data.type || data.data?.type || 'general';
      const options = createNotificationOptions(data, notificationType);

      event.waitUntil(
        Promise.all([
          showTargetedNotification(
            data.title || 'OhhSpaces Notification',
            options,
            notificationType
          ),
          playNotificationSound(notificationType),
          logNotificationEvent(data, 'received')
        ])
      );
    } catch (error) {
      console.error('[Service Worker] Error parsing push notification:', error);

      // Fallback notification
      const options = createFallbackOptions();
      event.waitUntil(
        self.registration.showNotification('OhhSpaces Notification', options)
      );
    }
  }
});

// ==================== NOTIFICATION OPTIONS ====================

/**
 * Creates notification options based on type and data
 * @param {Object} data - Notification payload from backend
 * @param {string} type - Notification type (booking_confirmed, etc.)
 * @returns {Object} Notification options
 */
function createNotificationOptions(data, type) {
  const baseOptions = {
    body: data.body || 'You have a new notification',
    icon: data.icon || '/icon-192x192.png',
    badge: '/icon-72x72.png',
    data: {
      url: data.url || '/',
      dateOfArrival: Date.now(),
      primaryKey: data.data?.id || '1',
      type: type,
      ...data.data
    },
    requireInteraction: false,
    silent: false, // CRITICAL: Must be false for system sound
    vibrate: [200, 100, 200]
  };

  // Customize based on notification type
  switch (type) {
    case 'booking_confirmed':
    case 'booking_reserved':
      return {
        ...baseOptions,
        vibrate: [100, 50, 100, 50, 100],
        actions: [
          {
            action: 'view_booking',
            title: 'View Booking',
            icon: '/icon-72x72.png'
          },
          {
            action: 'dismiss',
            title: 'Dismiss',
            icon: '/icon-72x72.png'
          }
        ],
        requireInteraction: true,
        tag: 'booking-confirmation'
      };

    case 'booking_reminder_checkin':
    case 'booking_reminder_checkout':
      return {
        ...baseOptions,
        vibrate: [200, 100, 200],
        actions: [
          {
            action: 'view_booking',
            title: 'View Details',
            icon: '/icon-72x72.png'
          },
          {
            action: 'snooze',
            title: 'Remind Later',
            icon: '/icon-72x72.png'
          }
        ],
        requireInteraction: true,
        tag: 'booking-reminder',
        renotify: true
      };

    case 'booking_cancelled':
      return {
        ...baseOptions,
        vibrate: [300, 200, 300],
        actions: [
          {
            action: 'view_refund',
            title: 'View Refund',
            icon: '/icon-72x72.png'
          },
          {
            action: 'dismiss',
            title: 'OK',
            icon: '/icon-72x72.png'
          }
        ],
        tag: 'booking-cancelled'
      };

    case 'refund_processed':
      return {
        ...baseOptions,
        vibrate: [100, 50, 100],
        actions: [
          {
            action: 'view_payment',
            title: 'View Details',
            icon: '/icon-72x72.png'
          },
          {
            action: 'dismiss',
            title: 'OK',
            icon: '/icon-72x72.png'
          }
        ],
        tag: 'refund-processed'
      };

    case 'seat_assigned':
    case 'seat_auto_assigned':
    case 'seat_reassigned':
      return {
        ...baseOptions,
        vibrate: [100, 50, 100],
        actions: [
          {
            action: 'view_booking',
            title: 'View Seat',
            icon: '/icon-72x72.png'
          },
          {
            action: 'dismiss',
            title: 'OK',
            icon: '/icon-72x72.png'
          }
        ],
        tag: 'seat-assignment'
      };

    case 'seat_removed':
      return {
        ...baseOptions,
        vibrate: [200, 100, 200],
        actions: [
          {
            action: 'view_bookings',
            title: 'View Bookings',
            icon: '/icon-72x72.png'
          },
          {
            action: 'dismiss',
            title: 'OK',
            icon: '/icon-72x72.png'
          }
        ],
        tag: 'seat-removed'
      };

    case 'beverage_order_new':
    case 'beverage_completed':
    case 'beverage_cancelled':
      return {
        ...baseOptions,
        vibrate: [100, 50, 100],
        actions: [
          {
            action: 'view_order',
            title: 'View Order',
            icon: '/icon-72x72.png'
          },
          {
            action: 'dismiss',
            title: 'OK',
            icon: '/icon-72x72.png'
          }
        ],
        tag: 'beverage-order'
      };

    default:
      return {
        ...baseOptions,
        vibrate: [100, 50, 100],
        actions: [
          {
            action: 'open',
            title: 'Open',
            icon: '/icon-72x72.png'
          },
          {
            action: 'dismiss',
            title: 'Dismiss',
            icon: '/icon-72x72.png'
          }
        ]
      };
  }
}

/**
 * Creates fallback notification options
 */
function createFallbackOptions() {
  return {
    body: 'You have a new notification from OhhSpaces',
    icon: '/icon-192x192.png',
    badge: '/icon-72x72.png',
    vibrate: [100, 50, 100],
    data: {
      url: '/',
      dateOfArrival: Date.now(),
      primaryKey: '1'
    }
  };
}

// ==================== NOTIFICATION DISPLAY ====================

/**
 * Show notification with targeted behavior
 */
async function showTargetedNotification(title, options, type) {
  // Replace existing notifications of the same type if needed
  if (options.tag) {
    const notifications = await self.registration.getNotifications({
      tag: options.tag
    });

    notifications.forEach(notification => {
      if (!options.renotify) {
        notification.close();
      }
    });
  }

  // Show the notification
  return self.registration.showNotification(title, options);
}

// ==================== SOUND HANDLING ====================

/**
 * Play notification sound by sending message to client
 */
async function playNotificationSound(type) {
  try {
    // Get all window clients
    const allClients = await clients.matchAll({
      includeUncontrolled: true,
      type: 'window'
    });

    // Send message to all clients to play sound
    allClients.forEach(client => {
      client.postMessage({
        type: 'PLAY_NOTIFICATION_SOUND',
        notificationType: type
      });
    });

    // If no clients are open, system sound will play
    return Promise.resolve();
  } catch (error) {
    console.error('[Service Worker] Error playing sound:', error);
    return Promise.resolve();
  }
}

// ==================== NOTIFICATION CLICK HANDLER ====================

self.addEventListener('notificationclick', function (event) {
  console.log('[Service Worker] Notification clicked:', event.action);

  event.notification.close();

  const notificationData = event.notification.data;
  const notificationType = notificationData.type || 'general';

  // Handle different actions based on notification type
  event.waitUntil(
    handleNotificationAction(event.action, notificationData, notificationType)
  );
});

/**
 * Handle different notification actions
 */
async function handleNotificationAction(action, data, type) {
  let urlToOpen = data.url || '/';

  // Handle type-specific actions
  switch (action) {
    case 'view_booking':
      urlToOpen = `/bookings/${data.bookingId || data.booking_id || ''}`;
      break;

    case 'view_bookings':
      urlToOpen = '/bookings';
      break;

    case 'view_refund':
    case 'view_payment':
      urlToOpen = `/bookings/${data.bookingId || data.booking_id || ''}`;
      break;

    case 'view_order':
      urlToOpen = '/beverages';
      break;

    case 'snooze':
      // Handle snooze by storing preference
      await handleSnoozeAction(data);
      return; // Don't open any window

    case 'dismiss':
    case 'close':
      // Just close, don't open anything
      await logNotificationEvent(data, 'dismissed');
      return;

    default:
      // Default action or no action specified
      urlToOpen = data.url || '/';
  }

  // Log action
  await logNotificationEvent(data, action || 'opened');

  // Open or focus the appropriate window
  return handleWindowOpen(urlToOpen);
}

/**
 * Handle snooze functionality
 */
async function handleSnoozeAction(data) {
  const snoozeTime = 15 * 60 * 1000; // 15 minutes

  // Store snooze preference in IndexedDB or notify backend
  console.log('[Service Worker] Snoozed notification for 15 minutes');

  // You could implement backend notification here
  // await fetch('/api/notifications/snooze', {
  //   method: 'POST',
  //   body: JSON.stringify({ notificationId: data.primaryKey, snoozeTime })
  // });
}

/**
 * Handle opening/focusing windows
 */
async function handleWindowOpen(urlToOpen) {
  const clientList = await clients.matchAll({
    type: 'window',
    includeUncontrolled: true
  });

  // Check if there is already a window/tab open with the target URL
  for (let i = 0; i < clientList.length; i++) {
    const client = clientList[i];
    if (client.url.includes(urlToOpen) && 'focus' in client) {
      return client.focus();
    }
  }

  // Check if any window is open to the app
  for (let i = 0; i < clientList.length; i++) {
    const client = clientList[i];
    if (client.url.includes(self.location.origin) && 'navigate' in client) {
      client.focus();
      return client.navigate(urlToOpen);
    }
  }

  // If not, then open the target URL in a new window/tab
  if (clients.openWindow) {
    return clients.openWindow(urlToOpen);
  }
}

// ==================== NOTIFICATION CLOSE HANDLER ====================

self.addEventListener('notificationclose', function (event) {
  console.log('[Service Worker] Notification closed');

  const notificationData = event.notification.data;
  event.waitUntil(logNotificationEvent(notificationData, 'closed'));
});

// ==================== LOGGING ====================

/**
 * Log notification events for analytics
 */
async function logNotificationEvent(data, action) {
  try {
    // You can send logs to your backend for analytics
    // await fetch('/api/notifications/log', {
    //   method: 'POST',
    //   headers: { 'Content-Type': 'application/json' },
    //   body: JSON.stringify({
    //     notificationId: data.primaryKey,
    //     type: data.type,
    //     action: action,
    //     timestamp: Date.now()
    //   })
    // });

    console.log(`[Service Worker] Notification ${action}:`, data.type);
  } catch (error) {
    console.error('[Service Worker] Failed to log event:', error);
  }
}

// ==================== BACKGROUND SYNC ====================

self.addEventListener('sync', function (event) {
  console.log('[Service Worker] Background sync:', event.tag);

  if (event.tag === 'sync-notifications') {
    event.waitUntil(doBackgroundSync());
  }
});

/**
 * Perform background sync operations
 */
async function doBackgroundSync() {
  try {
    // Sync pending actions when connection is restored
    console.log('[Service Worker] Performing background sync');

    // Example: Fetch missed notifications
    // const response = await fetch('/api/notifications/missed');
    // const data = await response.json();
    // Show missed notifications...

    return Promise.resolve();
  } catch (error) {
    console.error('[Service Worker] Background sync failed:', error);
    return Promise.reject(error);
  }
}

// ==================== INSTALL & ACTIVATE ====================

self.addEventListener('install', function (event) {
  console.log('[Service Worker] Installing version', CACHE_VERSION);

  // Skip waiting to activate immediately
  self.skipWaiting();

  event.waitUntil(
    caches.open(CACHE_NAME).then(cache => {
      return cache.addAll([
        '/',
        '/icon-192x192.png',
        '/icon-512x512.png',
        '/icon-72x72.png'
      ]);
    })
  );
});

self.addEventListener('activate', function (event) {
  console.log('[Service Worker] Activating version', CACHE_VERSION);

  event.waitUntil(
    Promise.all([
      // Claim all clients immediately
      clients.claim(),

      // Clean up old caches
      caches.keys().then(cacheNames => {
        return Promise.all(
          cacheNames.map(cacheName => {
            if (cacheName !== CACHE_NAME) {
              console.log('[Service Worker] Deleting old cache:', cacheName);
              return caches.delete(cacheName);
            }
          })
        );
      })
    ])
  );
});

// ==================== FETCH HANDLER (Optional) ====================

self.addEventListener('fetch', function (event) {
  // Optional: Add caching strategies here
  // For now, just use network-first approach
  event.respondWith(
    fetch(event.request).catch(() => {
      return caches.match(event.request);
    })
  );
});

PWA Manifest Configuration

public/manifest.json

A complete PWA manifest for installability and enhanced user experience.

{
  "name": "Your App Name",
  "short_name": "YourApp",
  "description": "Your app description - Book, manage, and stay connected with push notifications",
  "id": "/",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "orientation": "portrait-primary",
  "theme_color": "#006FEE",
  "background_color": "#ffffff",
  "lang": "en",
  "dir": "ltr",
  "categories": ["business", "productivity"],
  "icons": [
    {
      "src": "/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable"
    },
    {
      "src": "/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icon-72x72.png",
      "sizes": "72x72",
      "type": "image/png",
      "purpose": "any"
    }
  ],
  "screenshots": [
    {
      "src": "/screenshots/desktop.png",
      "sizes": "2880x1800",
      "type": "image/png",
      "form_factor": "wide",
      "label": "Desktop view"
    },
    {
      "src": "/screenshots/mobile.png",
      "sizes": "750x1334",
      "type": "image/png",
      "form_factor": "narrow",
      "label": "Mobile view"
    }
  ],
  "shortcuts": [
    {
      "name": "Book Now",
      "short_name": "Book",
      "description": "Quickly book a space",
      "url": "/?shortcut=book",
      "icons": [
        {
          "src": "/icon-192x192.png",
          "sizes": "192x192"
        }
      ]
    },
    {
      "name": "My Bookings",
      "short_name": "Bookings",
      "description": "View your bookings",
      "url": "/bookings?shortcut=my",
      "icons": [
        {
          "src": "/icon-192x192.png",
          "sizes": "192x192"
        }
      ]
    }
  ],
  "prefer_related_applications": false
}

Manifest Fields Explained

Field	Purpose	Required
`name`	Full app name (45 chars max)	✅
`short_name`	Short name for home screen (12 chars)	✅
`start_url`	URL to open when launched	✅
`display`	Display mode (standalone, fullscreen, minimal-ui)	✅
`icons`	App icons for different sizes	✅
`theme_color`	Browser UI color	Recommended
`background_color`	Splash screen color	Recommended
`orientation`	Default orientation	Optional
`shortcuts`	Quick actions from home screen	Optional
`screenshots`	For app stores	Optional

Notification Customization

Notification Options Reference

const notificationOptions = {
  // Basic Properties
  body: 'Notification body text',          // Main message
  icon: '/icon-192x192.png',               // Large icon (192x192)
  badge: '/icon-72x72.png',                // Small icon in status bar (72x72)
  image: '/notification-image.jpg',         // Large image below text

  // Behavior
  requireInteraction: false,                // Keep until user dismisses
  silent: false,                            // Play system sound (true = silent)
  vibrate: [200, 100, 200],                // Vibration pattern [vibrate, pause, vibrate]
  renotify: false,                          // Re-alert on same tag update

  // Grouping
  tag: 'booking-123',                       // Unique tag (replaces previous with same tag)

  // Data
  data: {                                   // Custom data passed to click handler
    url: '/bookings/123',
    bookingId: '123',
    userId: 'abc'
  },

  // Actions (max 2 on mobile, 4 on desktop)
  actions: [
    {
      action: 'view',
      title: 'View Details',
      icon: '/action-icon.png'
    },
    {
      action: 'dismiss',
      title: 'Dismiss',
      icon: '/dismiss-icon.png'
    }
  ],

  // Advanced
  timestamp: Date.now(),                    // When event occurred
  dir: 'auto',                              // Text direction (ltr, rtl, auto)
  lang: 'en',                               // Language code
};

Vibration Patterns

// Short tap
vibrate: [100]

// Double tap
vibrate: [100, 50, 100]

// Triple tap
vibrate: [100, 50, 100, 50, 100]

// Long vibration
vibrate: [500]

// SOS pattern
vibrate: [100, 30, 100, 30, 100, 200, 200, 30, 200, 30, 200, 200, 100, 30, 100, 30, 100]

// Custom rhythm
vibrate: [200, 100, 200, 100, 300]

Action Handlers

Custom Action Implementation

// In service worker
self.addEventListener('notificationclick', function (event) {
  event.notification.close();

  const action = event.action;
  const data = event.notification.data;

  event.waitUntil(
    handleCustomActions(action, data)
  );
});

async function handleCustomActions(action, data) {
  switch (action) {
    case 'accept':
      // Accept booking request
      await fetch('/api/bookings/accept', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ bookingId: data.bookingId })
      });

      // Show confirmation notification
      await self.registration.showNotification('Booking Accepted', {
        body: 'You accepted the booking request',
        icon: '/success-icon.png'
      });
      break;

    case 'reject':
      // Reject booking request
      await fetch('/api/bookings/reject', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ bookingId: data.bookingId })
      });
      break;

    case 'reply':
      // Open compose message
      return clients.openWindow(`/messages/compose?to=${data.userId}`);

    default:
      // Default: open app
      return clients.openWindow(data.url || '/');
  }
}

Background Sync

Registering Background Sync

// In your frontend code
async function registerBackgroundSync() {
  const registration = await navigator.serviceWorker.ready;

  try {
    await registration.sync.register('sync-notifications');
    console.log('Background sync registered');
  } catch (error) {
    console.error('Background sync failed:', error);
  }
}

Handling Background Sync in Service Worker

self.addEventListener('sync', function (event) {
  if (event.tag === 'sync-notifications') {
    event.waitUntil(syncNotifications());
  }
});

async function syncNotifications() {
  try {
    // Fetch missed notifications when back online
    const response = await fetch('/api/notifications/missed');
    const notifications = await response.json();

    // Show each missed notification
    for (const notif of notifications) {
      await self.registration.showNotification(notif.title, {
        body: notif.body,
        icon: notif.icon,
        data: notif.data
      });
    }

    return Promise.resolve();
  } catch (error) {
    // Retry later
    return Promise.reject(error);
  }
}

Offline Support

Cache Strategies

// In service worker - fetch event
self.addEventListener('fetch', function (event) {
  const url = new URL(event.request.url);

  // API requests: Network first, cache fallback
  if (url.pathname.startsWith('/api/')) {
    event.respondWith(
      fetch(event.request)
        .then(response => {
          // Clone and cache successful responses
          if (response.ok) {
            const responseToCache = response.clone();
            caches.open(CACHE_NAME).then(cache => {
              cache.put(event.request, responseToCache);
            });
          }
          return response;
        })
        .catch(() => {
          // Return cached version if available
          return caches.match(event.request);
        })
    );
    return;
  }

  // Static assets: Cache first, network fallback
  event.respondWith(
    caches.match(event.request).then(cachedResponse => {
      if (cachedResponse) {
        return cachedResponse;
      }
      return fetch(event.request);
    })
  );
});

Testing Service Workers

Chrome DevTools Testing

Open DevTools → Application → Service Workers
Check "Update on reload" - Forces SW update on page refresh
Unregister - Remove service worker completely
Push - Simulate push event (requires subscription)

Manual Push Test

// In browser console
navigator.serviceWorker.ready.then(registration => {
  registration.showNotification('Test Notification', {
    body: 'This is a test',
    icon: '/icon-192x192.png',
    data: { url: '/' }
  });
});

Automated Testing

// test-service-worker.js
const { test, expect } = require('@playwright/test');

test('service worker registers successfully', async ({ page }) => {
  await page.goto('http://localhost:3000');

  const swRegistered = await page.evaluate(async () => {
    const registration = await navigator.serviceWorker.ready;
    return registration.active !== null;
  });

  expect(swRegistered).toBe(true);
});

test('service worker shows notification', async ({ page, context }) => {
  await context.grantPermissions(['notifications']);
  await page.goto('http://localhost:3000');

  const notificationShown = await page.evaluate(async () => {
    const registration = await navigator.serviceWorker.ready;
    await registration.showNotification('Test', {
      body: 'Test body'
    });

    const notifications = await registration.getNotifications();
    return notifications.length > 0;
  });

  expect(notificationShown).toBe(true);
});

Debugging Tools

Service Worker Debugging Checklist

# 1. Check if service worker is registered
# Browser Console:
navigator.serviceWorker.getRegistrations().then(regs => console.log(regs));

# 2. Check service worker state
# Browser Console:
navigator.serviceWorker.ready.then(reg => console.log(reg.active.state));

# 3. Force update service worker
# Browser Console:
navigator.serviceWorker.getRegistrations().then(regs => {
  regs.forEach(reg => reg.update());
});

# 4. Unregister all service workers
# Browser Console:
navigator.serviceWorker.getRegistrations().then(regs => {
  regs.forEach(reg => reg.unregister());
});

Common Console Commands

// Check if push supported
console.log('Push supported:', 'PushManager' in window);

// Check notification permission
console.log('Notification permission:', Notification.permission);

// Get current subscription
navigator.serviceWorker.ready.then(async reg => {
  const sub = await reg.pushManager.getSubscription();
  console.log('Current subscription:', sub);
});

// Check service worker controller
console.log('Controlled by SW:', navigator.serviceWorker.controller);

Common Pitfalls

Issue 1: Service Worker Not Updating

Problem: Changes to sw.js not reflected.

Solution:

// Force update on page load
navigator.serviceWorker.register('/sw.js').then(reg => {
  reg.update();
});

// In service worker, use versioning
const CACHE_VERSION = 'v1.0.1'; // Increment on changes

Issue 2: Notifications Not Showing

Problem: showNotification() called but nothing appears.

Solution:

// ALWAYS check permission first
if (Notification.permission === 'granted') {
  registration.showNotification('Title', options);
} else {
  console.error('Permission not granted');
}

// Ensure `silent: false` in options
const options = {
  silent: false // System sound will play
};

Issue 3: Service Worker Scope Issues

Problem: Service worker not controlling pages.

Solution:

// Register at root for widest scope
navigator.serviceWorker.register('/sw.js', { scope: '/' });

// NOT:
navigator.serviceWorker.register('/js/sw.js'); // Limited to /js/*

Issue 4: iOS Safari Not Working

Problem: Push notifications don't work on iPhone.

Solution:

User MUST add app to home screen (PWA)
Open app from home screen icon (not browser)
Only works on iOS 16.4+ with Safari 16.4+
macOS Safari 16+ works normally

Detection Code:

const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent);
const isStandalone = window.navigator.standalone;

if (isIOS && !isStandalone) {
  // Show "Add to Home Screen" instructions
  alert('Please add this app to your home screen to enable notifications');
}

Summary

You now have:

✅ Complete service worker with push event handling
✅ PWA manifest for installability
✅ Custom notification options and actions
✅ Background sync implementation
✅ Offline support with caching
✅ Comprehensive testing guide
✅ Debugging tools and commands
✅ Common pitfall solutions

Next Steps

➡️ Part 5: Advanced Features & Production Deployment

Part 5 will cover:

Advanced targeting strategies
Notification scheduling
Rate limiting and throttling
Production deployment (Docker, Kubernetes)
SSL/HTTPS configuration
Load balancing
Horizontal scaling
Database optimization

# Self-Hosted Push Notifications Part-3

Bipin C — Wed, 22 Oct 2025 12:03:45 +0000

Self-Hosted Push Notifications Specification

Part 3: Frontend Implementation (Next.js)

Version: 1.0
Last Updated: October 2025
Prerequisites: Part 2: Backend Implementation
Author: Bunty9
License: MIT (Free to use and adapt)

Dependencies
TypeScript Type Definitions
API Routes (SSR)
Custom Hook
PushNotificationManager Component
Utility Functions
Integration in _app.tsx
Usage Examples
Troubleshooting

Dependencies

Install Required Packages

# Navigate to frontend directory
cd frontend

# Create Next.js app if you haven't already
npx create-next-app@latest . --typescript

# No additional packages needed!
# Push API is built into modern browsers

package.json (Relevant Dependencies)

{
  "dependencies": {
    "next": "^14.0.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "typescript": "^5.0.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "@types/react": "^18.2.0",
    "@types/react-dom": "^18.2.0"
  }
}

TypeScript Type Definitions

types/push.ts

// ==================== Request/Response Types ====================

export interface PushSubscriptionKeys {
  p256dh: string;
  auth: string;
}

export interface SubscribePushRequest {
  endpoint: string;
  keys: PushSubscriptionKeys;
  userAgent: string;
}

export interface SubscribePushResponse {
  success: boolean;
  message: string;
  subscriptionId: string;
  deviceId: string;
  deviceName: string;
}

export interface UnsubscribePushRequest {
  endpoint: string;
}

export interface DeviceInfo {
  id: string;
  deviceId: string;
  deviceName: string;
  browser: string;
  os: string;
  deviceType: 'mobile' | 'desktop' | 'tablet';
  isActive: boolean;
  lastUsedAt?: string;
  createdAt: string;
}

export interface GetDevicesResponse {
  success: boolean;
  count: number;
  devices: DeviceInfo[];
}

// ==================== Notification Payload ====================

export interface NotificationAction {
  action: string;
  title: string;
  icon?: string;
}

export interface PushPayload {
  title: string;
  body: string;
  icon?: string;
  badge?: string;
  image?: string;
  tag?: string;
  url?: string;
  data?: Record<string, any>;
  requireInteraction?: boolean;
  silent?: boolean;
  vibrate?: number[];
  actions?: NotificationAction[];
}

// ==================== Browser API Types ====================

export interface PushSubscriptionOptions {
  userVisibleOnly: boolean;
  applicationServerKey: Uint8Array;
}

// ==================== Component State ====================

export interface PushNotificationState {
  isSupported: boolean;
  permission: NotificationPermission;
  isSubscribed: boolean;
  isLoading: boolean;
  error: string | null;
}

API Routes (SSR)

These routes act as secure proxies to your Go backend, forwarding cookies for authentication.

pages/api/push/subscribe.ts

import type { NextApiRequest, NextApiResponse } from 'next';

const USER_SERVICE_URL = process.env.BACKEND_API_URL || 'http://localhost:8080';

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  try {
    const { endpoint, keys, userAgent } = req.body;

    // Validate request
    if (!endpoint || !keys || !keys.p256dh || !keys.auth) {
      return res.status(400).json({ error: 'Missing required fields' });
    }

    // Forward to backend with cookies
    const cookieHeader = req.headers.cookie || '';

    const response = await fetch(`${USER_SERVICE_URL}/api/push/subscribe`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Cookie': cookieHeader,  // Critical: Forward entire cookie header
      },
      body: JSON.stringify({
        endpoint,
        keys,
        userAgent: userAgent || req.headers['user-agent'] || '',
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json(data);
    }

    return res.status(200).json(data);
  } catch (error) {
    console.error('Subscribe error:', error);
    return res.status(500).json({
      error: 'Failed to subscribe to push notifications'
    });
  }
}

pages/api/push/unsubscribe.ts

import type { NextApiRequest, NextApiResponse } from 'next';

const USER_SERVICE_URL = process.env.BACKEND_API_URL || 'http://localhost:8080';

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  try {
    const { endpoint } = req.body;

    if (!endpoint) {
      return res.status(400).json({ error: 'Endpoint is required' });
    }

    const cookieHeader = req.headers.cookie || '';

    const response = await fetch(`${USER_SERVICE_URL}/api/push/unsubscribe`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Cookie': cookieHeader,
      },
      body: JSON.stringify({ endpoint }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json(data);
    }

    return res.status(200).json(data);
  } catch (error) {
    console.error('Unsubscribe error:', error);
    return res.status(500).json({
      error: 'Failed to unsubscribe from push notifications'
    });
  }
}

pages/api/push/devices.ts

import type { NextApiRequest, NextApiResponse } from 'next';

const USER_SERVICE_URL = process.env.BACKEND_API_URL || 'http://localhost:8080';

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== 'GET') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  try {
    const cookieHeader = req.headers.cookie || '';

    const response = await fetch(`${USER_SERVICE_URL}/api/push/devices`, {
      method: 'GET',
      headers: {
        'Cookie': cookieHeader,
      },
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json(data);
    }

    return res.status(200).json(data);
  } catch (error) {
    console.error('Get devices error:', error);
    return res.status(500).json({
      error: 'Failed to fetch devices'
    });
  }
}

Custom Hook

hooks/usePushNotifications.ts

A reusable React hook that encapsulates all push notification logic.

import { useState, useEffect, useCallback } from 'react';
import type { PushNotificationState, DeviceInfo } from '@/types/push';

const VAPID_PUBLIC_KEY = process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY || '';

export const usePushNotifications = () => {
  const [state, setState] = useState<PushNotificationState>({
    isSupported: false,
    permission: 'default',
    isSubscribed: false,
    isLoading: false,
    error: null,
  });

  // Check if push notifications are supported
  useEffect(() => {
    if (typeof window === 'undefined') return;

    const isSupported =
      'serviceWorker' in navigator &&
      'PushManager' in window &&
      'Notification' in window;

    setState((prev) => ({
      ...prev,
      isSupported,
      permission: isSupported ? Notification.permission : 'denied',
    }));
  }, []);

  // Check if already subscribed
  useEffect(() => {
    if (!state.isSupported) return;

    checkSubscription();
  }, [state.isSupported]);

  // Check if user is already subscribed
  const checkSubscription = async () => {
    try {
      const registration = await navigator.serviceWorker.ready;
      const subscription = await registration.pushManager.getSubscription();

      setState((prev) => ({
        ...prev,
        isSubscribed: subscription !== null,
        permission: Notification.permission,
      }));
    } catch (error) {
      console.error('Failed to check subscription:', error);
    }
  };

  // Request notification permission
  const requestPermission = async (): Promise<NotificationPermission> => {
    if (!state.isSupported) {
      throw new Error('Push notifications are not supported');
    }

    const permission = await Notification.requestPermission();
    setState((prev) => ({ ...prev, permission }));
    return permission;
  };

  // Subscribe to push notifications
  const subscribe = useCallback(async () => {
    setState((prev) => ({ ...prev, isLoading: true, error: null }));

    try {
      // Check support
      if (!state.isSupported) {
        throw new Error('Push notifications are not supported in this browser');
      }

      // Request permission if not granted
      if (Notification.permission === 'default') {
        const permission = await requestPermission();
        if (permission !== 'granted') {
          throw new Error('Notification permission denied');
        }
      } else if (Notification.permission !== 'granted') {
        throw new Error('Notification permission denied');
      }

      // Wait for service worker to be ready
      const registration = await navigator.serviceWorker.ready;

      // Subscribe to push manager
      const subscription = await registration.pushManager.subscribe({
        userVisibleOnly: true,
        applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY),
      });

      // Convert subscription to JSON
      const subscriptionJSON = subscription.toJSON();

      // Send subscription to backend
      const response = await fetch('/api/push/subscribe', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          endpoint: subscriptionJSON.endpoint,
          keys: {
            p256dh: subscriptionJSON.keys?.p256dh || '',
            auth: subscriptionJSON.keys?.auth || '',
          },
          userAgent: navigator.userAgent,
        }),
      });

      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.error || 'Failed to subscribe');
      }

      const data = await response.json();

      setState((prev) => ({
        ...prev,
        isSubscribed: true,
        isLoading: false,
        error: null,
      }));

      return data;
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Failed to subscribe';
      setState((prev) => ({
        ...prev,
        isLoading: false,
        error: errorMessage,
      }));
      throw error;
    }
  }, [state.isSupported]);

  // Unsubscribe from push notifications
  const unsubscribe = useCallback(async () => {
    setState((prev) => ({ ...prev, isLoading: true, error: null }));

    try {
      const registration = await navigator.serviceWorker.ready;
      const subscription = await registration.pushManager.getSubscription();

      if (!subscription) {
        throw new Error('No subscription found');
      }

      // Unsubscribe from push manager
      await subscription.unsubscribe();

      // Notify backend
      await fetch('/api/push/unsubscribe', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          endpoint: subscription.endpoint,
        }),
      });

      setState((prev) => ({
        ...prev,
        isSubscribed: false,
        isLoading: false,
        error: null,
      }));
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Failed to unsubscribe';
      setState((prev) => ({
        ...prev,
        isLoading: false,
        error: errorMessage,
      }));
      throw error;
    }
  }, []);

  // Get user's devices
  const getDevices = useCallback(async (): Promise<DeviceInfo[]> => {
    try {
      const response = await fetch('/api/push/devices');

      if (!response.ok) {
        throw new Error('Failed to fetch devices');
      }

      const data = await response.json();
      return data.data.devices || [];
    } catch (error) {
      console.error('Failed to get devices:', error);
      return [];
    }
  }, []);

  return {
    ...state,
    subscribe,
    unsubscribe,
    requestPermission,
    checkSubscription,
    getDevices,
  };
};

// ==================== Utility Functions ====================

/**
 * Converts a base64 URL-safe string to Uint8Array (required for VAPID key)
 */
function urlBase64ToUint8Array(base64String: string): Uint8Array {
  const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
  const base64 = (base64String + padding)
    .replace(/-/g, '+')
    .replace(/_/g, '/');

  const rawData = window.atob(base64);
  const outputArray = new Uint8Array(rawData.length);

  for (let i = 0; i < rawData.length; ++i) {
    outputArray[i] = rawData.charCodeAt(i);
  }
  return outputArray;
}

/**
 * Converts ArrayBuffer to base64 string
 */
function arrayBufferToBase64(buffer: ArrayBuffer | null): string {
  if (!buffer) return '';
  const bytes = new Uint8Array(buffer);
  let binary = '';
  for (let i = 0; i < bytes.byteLength; i++) {
    binary += String.fromCharCode(bytes[i]);
  }
  return window.btoa(binary);
}

PushNotificationManager Component

components/PushNotificationManager.tsx

A self-contained UI component that handles subscription management.

'use client';

import { useEffect, useState } from 'react';
import { usePushNotifications } from '@/hooks/usePushNotifications';

interface PushNotificationManagerProps {
  className?: string;
  showDismiss?: boolean;  // Allow users to dismiss the prompt
  autoHide?: boolean;     // Auto-hide after successful subscription
  autoHideDelay?: number; // Delay before auto-hide (ms)
}

export const PushNotificationManager = ({
  className = '',
  showDismiss = true,
  autoHide = true,
  autoHideDelay = 3000,
}: PushNotificationManagerProps) => {
  const {
    isSupported,
    permission,
    isSubscribed,
    isLoading,
    error,
    subscribe,
    unsubscribe,
  } = usePushNotifications();

  const [isVisible, setIsVisible] = useState(true);
  const [isClient, setIsClient] = useState(false);
  const [isDismissed, setIsDismissed] = useState(false);

  // Check if dismissed in localStorage
  useEffect(() => {
    setIsClient(true);
    const dismissed = localStorage.getItem('push-notification-dismissed');
    if (dismissed === 'true') {
      setIsDismissed(true);
      setIsVisible(false);
    }
  }, []);

  // Auto-hide after successful subscription
  useEffect(() => {
    if (isSubscribed && autoHide) {
      const timer = setTimeout(() => {
        setIsVisible(false);
      }, autoHideDelay);

      return () => clearTimeout(timer);
    }
  }, [isSubscribed, autoHide, autoHideDelay]);

  const handleSubscribe = async () => {
    try {
      await subscribe();
    } catch (error) {
      console.error('Failed to subscribe:', error);
    }
  };

  const handleUnsubscribe = async () => {
    try {
      await unsubscribe();
    } catch (error) {
      console.error('Failed to unsubscribe:', error);
    }
  };

  const handleDismiss = () => {
    setIsVisible(false);
    setIsDismissed(true);
    localStorage.setItem('push-notification-dismissed', 'true');
  };

  // Don't render on server
  if (!isClient) {
    return null;
  }

  // Don't show if dismissed or not visible
  if (!isVisible || isDismissed) {
    return null;
  }

  // Don't show if not supported
  if (!isSupported) {
    return null;
  }

  // Already subscribed - show success message
  if (isSubscribed) {
    return (
      <div className={`notification-banner success ${className}`}>
        <div className="notification-content">
          <div className="notification-icon">✅</div>
          <div className="notification-text">
            <p className="notification-title">Notifications Enabled</p>
            <p className="notification-body">
              You'll receive important updates and notifications
            </p>
          </div>
        </div>
        <div className="notification-actions">
          <button
            onClick={handleUnsubscribe}
            className="btn-secondary"
            disabled={isLoading}
          >
            Unsubscribe
          </button>
          {showDismiss && (
            <button onClick={handleDismiss} className="btn-close">
              ×
            </button>
          )}
        </div>
      </div>
    );
  }

  // Permission denied
  if (permission === 'denied') {
    return (
      <div className={`notification-banner warning ${className}`}>
        <div className="notification-content">
          <div className="notification-icon">⚠️</div>
          <div className="notification-text">
            <p className="notification-title">Notifications Blocked</p>
            <p className="notification-body">
              You've blocked notifications. Enable them in your browser settings.
            </p>
          </div>
        </div>
        {showDismiss && (
          <button onClick={handleDismiss} className="btn-close">
            ×
          </button>
        )}
      </div>
    );
  }

  // Prompt to enable notifications
  return (
    <div className={`notification-banner info ${className}`}>
      <div className="notification-content">
        <div className="notification-icon">🔔</div>
        <div className="notification-text">
          <p className="notification-title">Stay Updated</p>
          <p className="notification-body">
            Enable notifications to receive important updates
          </p>
        </div>
      </div>
      <div className="notification-actions">
        <button
          onClick={handleSubscribe}
          className="btn-primary"
          disabled={isLoading}
        >
          {isLoading ? 'Enabling...' : 'Enable Notifications'}
        </button>
        {showDismiss && (
          <button onClick={handleDismiss} className="btn-close">
            ×
          </button>
        )}
      </div>
      {error && (
        <div className="notification-error">
          <p>{error}</p>
        </div>
      )}
    </div>
  );
};

// ==================== Styles ====================

// Add to your global CSS or styled-components

/*
.notification-banner {
  position: fixed;
  bottom: 20px;
  right: 20px;
  max-width: 400px;
  padding: 16px;
  border-radius: 8px;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  background: white;
  z-index: 1000;
  animation: slideIn 0.3s ease-out;
}

@keyframes slideIn {
  from {
    transform: translateY(100%);
    opacity: 0;
  }
  to {
    transform: translateY(0);
    opacity: 1;
  }
}

.notification-banner.success {
  border-left: 4px solid #10b981;
}

.notification-banner.warning {
  border-left: 4px solid #f59e0b;
}

.notification-banner.info {
  border-left: 4px solid #3b82f6;
}

.notification-content {
  display: flex;
  align-items: start;
  gap: 12px;
  margin-bottom: 12px;
}

.notification-icon {
  font-size: 24px;
  flex-shrink: 0;
}

.notification-text {
  flex: 1;
}

.notification-title {
  font-weight: 600;
  margin-bottom: 4px;
}

.notification-body {
  font-size: 14px;
  color: #6b7280;
}

.notification-actions {
  display: flex;
  gap: 8px;
  align-items: center;
  justify-content: flex-end;
}

.btn-primary {
  padding: 8px 16px;
  background: #3b82f6;
  color: white;
  border: none;
  border-radius: 6px;
  cursor: pointer;
  font-weight: 500;
}

.btn-primary:hover {
  background: #2563eb;
}

.btn-primary:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

.btn-secondary {
  padding: 8px 16px;
  background: #f3f4f6;
  color: #374151;
  border: none;
  border-radius: 6px;
  cursor: pointer;
  font-weight: 500;
}

.btn-secondary:hover {
  background: #e5e7eb;
}

.btn-close {
  background: none;
  border: none;
  font-size: 24px;
  cursor: pointer;
  color: #9ca3af;
  padding: 0;
  width: 24px;
  height: 24px;
  display: flex;
  align-items: center;
  justify-content: center;
}

.btn-close:hover {
  color: #6b7280;
}

.notification-error {
  margin-top: 8px;
  padding: 8px;
  background: #fee2e2;
  border-radius: 4px;
  font-size: 14px;
  color: #991b1b;
}

@media (max-width: 640px) {
  .notification-banner {
    bottom: 0;
    right: 0;
    left: 0;
    max-width: none;
    border-radius: 0;
  }
}
*/

Utility Functions

utils/push-utils.ts

/**
 * Registers the service worker
 */
export async function registerServiceWorker(): Promise<ServiceWorkerRegistration | null> {
  if ('serviceWorker' in navigator) {
    try {
      const registration = await navigator.serviceWorker.register('/sw.js');
      console.log('Service Worker registered:', registration);
      return registration;
    } catch (error) {
      console.error('Service Worker registration failed:', error);
      return null;
    }
  }
  return null;
}

/**
 * Checks if push notifications are supported
 */
export function isPushNotificationSupported(): boolean {
  return (
    typeof window !== 'undefined' &&
    'serviceWorker' in navigator &&
    'PushManager' in window &&
    'Notification' in window
  );
}

/**
 * Gets the current notification permission
 */
export function getNotificationPermission(): NotificationPermission {
  if (typeof window === 'undefined' || !('Notification' in window)) {
    return 'denied';
  }
  return Notification.permission;
}

/**
 * Checks if user is subscribed to push notifications
 */
export async function isSubscribed(): Promise<boolean> {
  if (!isPushNotificationSupported()) {
    return false;
  }

  try {
    const registration = await navigator.serviceWorker.ready;
    const subscription = await registration.pushManager.getSubscription();
    return subscription !== null;
  } catch (error) {
    console.error('Failed to check subscription status:', error);
    return false;
  }
}

/**
 * Shows a local notification (for testing)
 */
export async function showLocalNotification(
  title: string,
  body: string,
  options?: NotificationOptions
): Promise<void> {
  if (!isPushNotificationSupported()) {
    throw new Error('Notifications not supported');
  }

  if (Notification.permission !== 'granted') {
    throw new Error('Notification permission not granted');
  }

  const registration = await navigator.serviceWorker.ready;
  await registration.showNotification(title, {
    body,
    ...options,
  });
}

Integration in _app.tsx

pages/_app.tsx

import { useEffect } from 'react';
import type { AppProps } from 'next/app';
import { PushNotificationManager } from '@/components/PushNotificationManager';
import { registerServiceWorker } from '@/utils/push-utils';
import '@/styles/globals.css';

export default function App({ Component, pageProps }: AppProps) {
  // Register service worker on app mount
  useEffect(() => {
    registerServiceWorker();
  }, []);

  return (
    <>
      <Component {...pageProps} />

      {/* Add PushNotificationManager globally */}
      <PushNotificationManager
        showDismiss={true}
        autoHide={true}
        autoHideDelay={3000}
      />
    </>
  );
}

pages/_document.tsx

CRITICAL: Link PWA manifest in HTML head.

import { Html, Head, Main, NextScript } from 'next/document';

export default function Document() {
  return (
    <Html lang="en">
      <Head>
        {/* PWA Manifest - REQUIRED for notifications */}
        <link rel="manifest" href="/manifest.json" />

        {/* PWA Icons */}
        <link rel="icon" href="/favicon.ico" />
        <link rel="apple-touch-icon" href="/icon-192x192.png" />

        {/* Theme Color */}
        <meta name="theme-color" content="#3b82f6" />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

Usage Examples

Example 1: Programmatic Notification

// In any component
import { usePushNotifications } from '@/hooks/usePushNotifications';

export function MyComponent() {
  const { subscribe, isSubscribed, isLoading } = usePushNotifications();

  const handleEnableNotifications = async () => {
    try {
      await subscribe();
      alert('Notifications enabled!');
    } catch (error) {
      alert('Failed to enable notifications');
    }
  };

  return (
    <button onClick={handleEnableNotifications} disabled={isLoading || isSubscribed}>
      {isSubscribed ? 'Notifications Enabled' : 'Enable Notifications'}
    </button>
  );
}

Example 2: Device Management UI

import { useEffect, useState } from 'react';
import { usePushNotifications } from '@/hooks/usePushNotifications';
import type { DeviceInfo } from '@/types/push';

export function DeviceList() {
  const { getDevices } = usePushNotifications();
  const [devices, setDevices] = useState<DeviceInfo[]>([]);

  useEffect(() => {
    fetchDevices();
  }, []);

  const fetchDevices = async () => {
    const deviceList = await getDevices();
    setDevices(deviceList);
  };

  return (
    <div className="device-list">
      <h3>Your Devices ({devices.length}/5)</h3>
      {devices.map((device) => (
        <div key={device.id} className="device-card">
          <div className="device-info">
            <h4>{device.deviceName}</h4>
            <p>{device.browser} • {device.os}</p>
            <p className="device-date">
              Last used: {device.lastUsedAt ? new Date(device.lastUsedAt).toLocaleDateString() : 'Never'}
            </p>
          </div>
          <div className="device-status">
            {device.isActive ? (
              <span className="status-active">Active</span>
            ) : (
              <span className="status-inactive">Inactive</span>
            )}
          </div>
        </div>
      ))}
    </div>
  );
}

Example 3: Conditional Rendering

import { usePushNotifications } from '@/hooks/usePushNotifications';

export function NotificationBell() {
  const { isSupported, isSubscribed, permission } = usePushNotifications();

  // Don't show bell if not supported
  if (!isSupported) {
    return null;
  }

  return (
    <button className="notification-bell">
      🔔
      {isSubscribed ? (
        <span className="badge">✓</span>
      ) : permission === 'denied' ? (
        <span className="badge">✗</span>
      ) : (
        <span className="badge">!</span>
      )}
    </button>
  );
}

Example 4: Backend-Triggered Notification

// Backend logic (Go) - when booking is confirmed
func (bs *BookingService) ConfirmBooking(bookingID uuid.UUID) error {
    // ... confirm booking logic ...

    // Send push notification
    payload := types.PushPayload{
        Title: "Booking Confirmed!",
        Body:  fmt.Sprintf("Your booking at %s is confirmed", spaceName),
        Icon:  "/icon-192x192.png",
        Tag:   "booking_confirmed",
        URL:   fmt.Sprintf("/bookings/%s", bookingID),
        Data: map[string]interface{}{
            "bookingId": bookingID.String(),
            "type": "booking_confirmed",
        },
    }

    // Non-blocking send
    go pushService.SendToUser(userID, payload)

    return nil
}

Troubleshooting

Issue 1: "Service worker registration failed"

Cause: Service worker file not found or HTTPS not enabled.

Solution:

# Check file exists
ls public/sw.js

# Development: Next.js serves /public at root
# Access at: http://localhost:3000/sw.js

# Production: Ensure HTTPS is enabled

Issue 2: "Notification permission denied"

Cause: User clicked "Block" or "Deny".

Solution:

User must manually reset permissions in browser settings
Chrome: Settings → Privacy → Site Settings → Notifications
Firefox: Preferences → Privacy → Permissions → Notifications

Issue 3: "VAPID public key not configured"

Cause: Missing environment variable.

Solution:

# Create .env.local
echo "NEXT_PUBLIC_VAPID_PUBLIC_KEY=YOUR_PUBLIC_KEY_HERE" > .env.local

# Restart dev server
npm run dev

Issue 4: "Failed to subscribe: DOMException"

Cause: VAPID key mismatch or invalid format.

Solution:

// Verify key in hook
console.log('VAPID Key:', process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY);

// Ensure it's the same as backend
// Should be base64 URL-safe string, ~88 characters

Issue 5: "Notifications don't work on iOS"

Cause: iOS Safari requires PWA installation.

Solution:

User must "Add to Home Screen"
Open app from home screen icon (not browser)
Then notifications will work

Detection Code:

const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent);
const isStandalone = (window.navigator as any).standalone;

if (isIOS && !isStandalone) {
  // Show "Add to Home Screen" instruction
}

Issue 6: "Subscription works but no notifications received"

Cause: Service worker not handling push events.

Solution:

Check service worker is registered: Chrome DevTools → Application → Service Workers
Verify push event listener exists in sw.js
Test with backend /api/push/test/:userId endpoint

Next Steps

✅ Frontend implementation complete!

Now proceed to:

➡️ Part 4: Service Worker & PWA Configuration

Part 4 will cover:

Complete service worker implementation
Push event handling
Notification display customization
Click handlers and actions
PWA manifest configuration
Offline support
Background sync (advanced)

Summary

You now have a complete, production-ready frontend for push notifications with:

✅ Type-safe API routes with cookie forwarding
✅ Reusable usePushNotifications hook
✅ PushNotificationManager component with UI
✅ Multi-device support
✅ Automatic permission handling
✅ Error boundaries and fallbacks
✅ localStorage persistence for dismissed prompts
✅ Comprehensive utility functions

The frontend seamlessly integrates with your Go backend through SSR API routes.

# Self-Hosted Push Notifications Part-2

Bipin C — Wed, 22 Oct 2025 12:00:54 +0000

Self-Hosted Push Notifications Specification

Part 2: Backend Implementation (Go)

Version: 1.0
Last Updated: October 2025
Prerequisites: Part 1: Architecture & Setup
Author: Bunty9
License: MIT (Free to use and adapt)

Dependencies
GORM Models
Type Definitions
Push Service Implementation
HTTP Controllers
Route Configuration
Middleware
Utilities
Main Application
Testing

Dependencies

Install Required Packages

# Navigate to backend directory
cd backend

# Initialize Go module (if not already done)
go mod init github.com/yourusername/your-app

# Install core dependencies
go get github.com/gin-gonic/gin                      # HTTP framework
go get gorm.io/gorm                                  # ORM
go get gorm.io/driver/postgres                       # PostgreSQL driver
go get github.com/SherClockHolmes/webpush-go         # Web Push Protocol
go get github.com/google/uuid                        # UUID generation
go get github.com/joho/godotenv                      # Environment variables
go get github.com/golang-jwt/jwt/v5                  # JWT authentication

# Optional but recommended
go get github.com/gin-contrib/cors                   # CORS middleware
go get golang.org/x/time/rate                        # Rate limiting
go get github.com/sirupsen/logrus                    # Structured logging

go.mod Example

module github.com/yourusername/your-app

go 1.21

require (
    github.com/SherClockHolmes/webpush-go v1.3.0
    github.com/gin-contrib/cors v1.5.0
    github.com/gin-gonic/gin v1.9.1
    github.com/golang-jwt/jwt/v5 v5.2.0
    github.com/google/uuid v1.5.0
    github.com/joho/godotenv v1.5.1
    github.com/sirupsen/logrus v1.9.3
    golang.org/x/time v0.5.0
    gorm.io/driver/postgres v1.5.4
    gorm.io/gorm v1.25.5
)

GORM Models

models/push_subscription.go

package models

import (
    "time"

    "github.com/google/uuid"
    "gorm.io/gorm"
)

// PushSubscription represents a push notification subscription for a device
type PushSubscription struct {
    ID uuid.UUID `gorm:"type:uuid;primary_key;default:gen_random_uuid()" json:"id"`

    // User/Admin Association (mutually exclusive)
    UserID  *uuid.UUID `gorm:"type:uuid;index" json:"user_id,omitempty"`
    AdminID *uuid.UUID `gorm:"type:uuid;index" json:"admin_id,omitempty"`

    // Push Subscription Data (from browser)
    Endpoint   string `gorm:"type:text;not null;uniqueIndex" json:"endpoint"`
    P256dhKey  string `gorm:"type:text;not null" json:"p256dh_key"`
    AuthKey    string `gorm:"type:text;not null" json:"auth_key"`

    // Device Metadata
    DeviceID   string `gorm:"type:varchar(255);index" json:"device_id,omitempty"`
    DeviceName string `gorm:"type:varchar(255)" json:"device_name,omitempty"`
    DeviceType string `gorm:"type:varchar(50)" json:"device_type,omitempty"`   // mobile, desktop, tablet
    Browser    string `gorm:"type:varchar(50)" json:"browser,omitempty"`       // Chrome, Firefox, Safari
    OS         string `gorm:"type:varchar(50)" json:"os,omitempty"`            // Windows, macOS, Linux
    UserAgent  string `gorm:"type:text" json:"user_agent,omitempty"`

    // Health & Lifecycle
    IsActive     bool       `gorm:"not null;default:true;index" json:"is_active"`
    FailureCount int        `gorm:"not null;default:0" json:"failure_count"`
    LastUsedAt   *time.Time `gorm:"type:timestamp;index" json:"last_used_at,omitempty"`

    // Timestamps
    CreatedAt time.Time `gorm:"not null;default:now()" json:"created_at"`
    UpdatedAt time.Time `gorm:"not null;default:now()" json:"updated_at"`
}

// TableName specifies the table name for GORM
func (PushSubscription) TableName() string {
    return "push_subscriptions"
}

// BeforeCreate hook to generate UUID if not set
func (ps *PushSubscription) BeforeCreate(tx *gorm.DB) error {
    if ps.ID == uuid.Nil {
        ps.ID = uuid.New()
    }
    return nil
}

// IsUser returns true if this subscription belongs to a user (not admin)
func (ps *PushSubscription) IsUser() bool {
    return ps.UserID != nil && ps.AdminID == nil
}

// IsAdmin returns true if this subscription belongs to an admin
func (ps *PushSubscription) IsAdmin() bool {
    return ps.AdminID != nil && ps.UserID == nil
}

// GetOwnerID returns the UUID of the owner (user or admin)
func (ps *PushSubscription) GetOwnerID() uuid.UUID {
    if ps.UserID != nil {
        return *ps.UserID
    }
    if ps.AdminID != nil {
        return *ps.AdminID
    }
    return uuid.Nil
}

models/push_notification_log.go

package models

import (
    "time"

    "github.com/google/uuid"
    "gorm.io/datatypes"
    "gorm.io/gorm"
)

// PushNotificationLog represents an audit log for push notification attempts
type PushNotificationLog struct {
    ID uuid.UUID `gorm:"type:uuid;primary_key;default:gen_random_uuid()" json:"id"`

    // Relations
    SubscriptionID *uuid.UUID `gorm:"type:uuid;index" json:"subscription_id,omitempty"`
    UserID         *uuid.UUID `gorm:"type:uuid;index" json:"user_id,omitempty"`
    AdminID        *uuid.UUID `gorm:"type:uuid;index" json:"admin_id,omitempty"`

    // Notification Content
    Title   string         `gorm:"type:varchar(255)" json:"title"`
    Body    string         `gorm:"type:text" json:"body"`
    Payload datatypes.JSON `gorm:"type:jsonb" json:"payload,omitempty"`

    // Delivery Status
    Status         string `gorm:"type:varchar(50);not null;index" json:"status"` // sent, failed, expired
    ErrorMessage   string `gorm:"type:text" json:"error_message,omitempty"`
    HTTPStatusCode int    `gorm:"type:integer" json:"http_status_code,omitempty"`

    // Timestamps
    SentAt    time.Time `gorm:"not null;default:now();index" json:"sent_at"`
    CreatedAt time.Time `gorm:"not null;default:now()" json:"created_at"`
}

// TableName specifies the table name for GORM
func (PushNotificationLog) TableName() string {
    return "push_notification_logs"
}

// BeforeCreate hook to generate UUID if not set
func (pnl *PushNotificationLog) BeforeCreate(tx *gorm.DB) error {
    if pnl.ID == uuid.Nil {
        pnl.ID = uuid.New()
    }
    return nil
}

Type Definitions

types/push_types.go

package types

import (
    "github.com/google/uuid"
)

// ==================== Request Types ====================

// SubscribePushRequest represents the request to subscribe to push notifications
type SubscribePushRequest struct {
    Endpoint  string           `json:"endpoint" binding:"required"`
    Keys      SubscriptionKeys `json:"keys" binding:"required"`
    UserAgent string           `json:"userAgent"`
}

// SubscriptionKeys contains the encryption keys from the browser
type SubscriptionKeys struct {
    P256dh string `json:"p256dh" binding:"required"`
    Auth   string `json:"auth" binding:"required"`
}

// UnsubscribePushRequest represents the request to unsubscribe
type UnsubscribePushRequest struct {
    Endpoint string `json:"endpoint" binding:"required"`
}

// SendPushRequest represents a request to send a push notification
type SendPushRequest struct {
    UserID   *uuid.UUID  `json:"userId,omitempty"`
    AdminID  *uuid.UUID  `json:"adminId,omitempty"`
    DeviceID *string     `json:"deviceId,omitempty"`
    Payload  PushPayload `json:"payload" binding:"required"`
}

// ==================== Response Types ====================

// SubscribePushResponse represents the response after subscribing
type SubscribePushResponse struct {
    Success        bool       `json:"success"`
    Message        string     `json:"message"`
    SubscriptionID uuid.UUID  `json:"subscriptionId"`
    DeviceID       string     `json:"deviceId"`
    DeviceName     string     `json:"deviceName"`
}

// UnsubscribePushResponse represents the response after unsubscribing
type UnsubscribePushResponse struct {
    Success bool   `json:"success"`
    Message string `json:"message"`
}

// SendPushResponse represents the response after sending a notification
type SendPushResponse struct {
    Success       bool   `json:"success"`
    Message       string `json:"message"`
    DevicesSent   int    `json:"devicesSent"`
    DevicesFailed int    `json:"devicesFailed"`
}

// GetDevicesResponse represents the list of user devices
type GetDevicesResponse struct {
    Success bool                   `json:"success"`
    Count   int                    `json:"count"`
    Devices []DeviceInfo           `json:"devices"`
}

// DeviceInfo represents device information
type DeviceInfo struct {
    ID         uuid.UUID  `json:"id"`
    DeviceID   string     `json:"deviceId"`
    DeviceName string     `json:"deviceName"`
    Browser    string     `json:"browser"`
    OS         string     `json:"os"`
    DeviceType string     `json:"deviceType"`
    IsActive   bool       `json:"isActive"`
    LastUsedAt *time.Time `json:"lastUsedAt,omitempty"`
    CreatedAt  time.Time  `json:"createdAt"`
}

// ==================== Payload Types ====================

// PushPayload represents the notification payload sent to browsers
type PushPayload struct {
    Title string                 `json:"title" binding:"required"`
    Body  string                 `json:"body" binding:"required"`
    Icon  string                 `json:"icon,omitempty"`
    Badge string                 `json:"badge,omitempty"`
    Image string                 `json:"image,omitempty"`
    Tag   string                 `json:"tag,omitempty"`    // For notification grouping/replacement
    URL   string                 `json:"url,omitempty"`    // Where to navigate on click
    Data  map[string]interface{} `json:"data,omitempty"`   // Custom data

    // Advanced Options
    RequireInteraction bool     `json:"requireInteraction,omitempty"`
    Silent             bool     `json:"silent,omitempty"`
    Vibrate            []int    `json:"vibrate,omitempty"`
    Actions            []Action `json:"actions,omitempty"`
}

// Action represents a notification action button
type Action struct {
    Action string `json:"action"`
    Title  string `json:"title"`
    Icon   string `json:"icon,omitempty"`
}

// ==================== Internal Types ====================

// DeviceMetadata contains parsed device information from user agent
type DeviceMetadata struct {
    DeviceName string
    Browser    string
    OS         string
    DeviceType string
}

Push Service Implementation

services/push_service.go

This is the core service that handles all push notification operations.

package services

import (
    "encoding/json"
    "errors"
    "fmt"
    "log"
    "os"
    "strings"
    "time"

    "github.com/SherClockHolmes/webpush-go"
    "github.com/google/uuid"
    "gorm.io/gorm"

    "your-app/models"
    "your-app/types"
    "your-app/utils"
)

// PushService handles all push notification operations
type PushService struct {
    db              *gorm.DB
    vapidPublicKey  string
    vapidPrivateKey string
    vapidSubject    string
}

// NewPushService creates a new PushService instance
func NewPushService(db *gorm.DB) *PushService {
    return &PushService{
        db:              db,
        vapidPublicKey:  os.Getenv("VAPID_PUBLIC_KEY"),
        vapidPrivateKey: os.Getenv("VAPID_PRIVATE_KEY"),
        vapidSubject:    os.Getenv("VAPID_SUBJECT"),
    }
}

// ==================== SUBSCRIPTION MANAGEMENT ====================

// Subscribe creates or updates a push subscription
func (ps *PushService) Subscribe(userID *uuid.UUID, adminID *uuid.UUID, req types.SubscribePushRequest) (*types.SubscribePushResponse, error) {
    // Validate that either userID or adminID is provided (not both, not neither)
    if (userID == nil && adminID == nil) || (userID != nil && adminID != nil) {
        return nil, errors.New("must provide either userID or adminID, not both")
    }

    // Validate endpoint
    if !strings.HasPrefix(req.Endpoint, "https://") {
        return nil, errors.New("invalid endpoint: must use HTTPS")
    }

    // Parse device metadata from user agent
    deviceMetadata := utils.ParseUserAgent(req.UserAgent)

    // Check if subscription already exists (by endpoint)
    var existingSubscription models.PushSubscription
    err := ps.db.Where("endpoint = ?", req.Endpoint).First(&existingSubscription).Error

    if err == nil {
        // Update existing subscription
        existingSubscription.P256dhKey = req.Keys.P256dh
        existingSubscription.AuthKey = req.Keys.Auth
        existingSubscription.UserAgent = req.UserAgent
        existingSubscription.DeviceName = deviceMetadata.DeviceName
        existingSubscription.Browser = deviceMetadata.Browser
        existingSubscription.OS = deviceMetadata.OS
        existingSubscription.DeviceType = deviceMetadata.DeviceType
        existingSubscription.IsActive = true
        existingSubscription.FailureCount = 0
        existingSubscription.UpdatedAt = time.Now()

        if err := ps.db.Save(&existingSubscription).Error; err != nil {
            return nil, fmt.Errorf("failed to update subscription: %w", err)
        }

        return &types.SubscribePushResponse{
            Success:        true,
            Message:        "Subscription updated successfully",
            SubscriptionID: existingSubscription.ID,
            DeviceID:       existingSubscription.DeviceID,
            DeviceName:     existingSubscription.DeviceName,
        }, nil
    }

    // Check device limit (5 devices per user/admin)
    var count int64
    query := ps.db.Model(&models.PushSubscription{}).Where("is_active = ?", true)
    if userID != nil {
        query = query.Where("user_id = ?", userID)
    } else {
        query = query.Where("admin_id = ?", adminID)
    }
    query.Count(&count)

    if count >= 5 {
        return nil, errors.New("device limit reached (maximum 5 devices)")
    }

    // Create new subscription
    subscription := models.PushSubscription{
        UserID:     userID,
        AdminID:    adminID,
        Endpoint:   req.Endpoint,
        P256dhKey:  req.Keys.P256dh,
        AuthKey:    req.Keys.Auth,
        DeviceID:   uuid.New().String(), // Generate unique device ID
        DeviceName: deviceMetadata.DeviceName,
        Browser:    deviceMetadata.Browser,
        OS:         deviceMetadata.OS,
        DeviceType: deviceMetadata.DeviceType,
        UserAgent:  req.UserAgent,
        IsActive:   true,
    }

    if err := ps.db.Create(&subscription).Error; err != nil {
        return nil, fmt.Errorf("failed to create subscription: %w", err)
    }

    log.Printf("[PushService] New subscription created: %s (%s)", subscription.DeviceName, subscription.ID)

    return &types.SubscribePushResponse{
        Success:        true,
        Message:        "Subscribed successfully",
        SubscriptionID: subscription.ID,
        DeviceID:       subscription.DeviceID,
        DeviceName:     subscription.DeviceName,
    }, nil
}

// Unsubscribe removes a push subscription by endpoint
func (ps *PushService) Unsubscribe(endpoint string) error {
    result := ps.db.Where("endpoint = ?", endpoint).Delete(&models.PushSubscription{})
    if result.Error != nil {
        return fmt.Errorf("failed to unsubscribe: %w", result.Error)
    }
    if result.RowsAffected == 0 {
        return errors.New("subscription not found")
    }
    log.Printf("[PushService] Subscription unsubscribed: %s", endpoint)
    return nil
}

// GetUserDevices returns all active devices for a user
func (ps *PushService) GetUserDevices(userID uuid.UUID) ([]types.DeviceInfo, error) {
    var subscriptions []models.PushSubscription
    err := ps.db.Where("user_id = ? AND is_active = ?", userID, true).
        Order("last_used_at DESC").
        Find(&subscriptions).Error

    if err != nil {
        return nil, err
    }

    devices := make([]types.DeviceInfo, len(subscriptions))
    for i, sub := range subscriptions {
        devices[i] = types.DeviceInfo{
            ID:         sub.ID,
            DeviceID:   sub.DeviceID,
            DeviceName: sub.DeviceName,
            Browser:    sub.Browser,
            OS:         sub.OS,
            DeviceType: sub.DeviceType,
            IsActive:   sub.IsActive,
            LastUsedAt: sub.LastUsedAt,
            CreatedAt:  sub.CreatedAt,
        }
    }

    return devices, nil
}

// ==================== SENDING NOTIFICATIONS ====================

// SendToUser sends a notification to all active devices of a user
func (ps *PushService) SendToUser(userID uuid.UUID, payload types.PushPayload) error {
    var subscriptions []models.PushSubscription
    err := ps.db.Where("user_id = ? AND is_active = ?", userID, true).
        Find(&subscriptions).Error

    if err != nil {
        return fmt.Errorf("failed to fetch subscriptions: %w", err)
    }

    if len(subscriptions) == 0 {
        log.Printf("[PushService] No active subscriptions for user: %s", userID)
        return nil // Not an error, just no devices
    }

    // Send to all devices in parallel using goroutines
    for _, subscription := range subscriptions {
        go ps.sendToSubscription(subscription, payload)
    }

    return nil
}

// SendToUserDevice sends a notification to a specific user device
func (ps *PushService) SendToUserDevice(userID uuid.UUID, deviceID string, payload types.PushPayload) error {
    var subscription models.PushSubscription
    err := ps.db.Where("user_id = ? AND device_id = ? AND is_active = ?", userID, deviceID, true).
        First(&subscription).Error

    if err != nil {
        return fmt.Errorf("device not found: %w", err)
    }

    return ps.sendToSubscription(subscription, payload)
}

// SendToAdmin sends a notification to all active devices of an admin
func (ps *PushService) SendToAdmin(adminID uuid.UUID, payload types.PushPayload) error {
    var subscriptions []models.PushSubscription
    err := ps.db.Where("admin_id = ? AND is_active = ?", adminID, true).
        Find(&subscriptions).Error

    if err != nil {
        return fmt.Errorf("failed to fetch subscriptions: %w", err)
    }

    if len(subscriptions) == 0 {
        log.Printf("[PushService] No active subscriptions for admin: %s", adminID)
        return nil
    }

    for _, subscription := range subscriptions {
        go ps.sendToSubscription(subscription, payload)
    }

    return nil
}

// SendBroadcastToAllUsers sends a notification to all active user subscriptions
func (ps *PushService) SendBroadcastToAllUsers(payload types.PushPayload) error {
    return ps.sendBroadcast("user_id IS NOT NULL", payload)
}

// SendBroadcastToAllAdmins sends a notification to all active admin subscriptions
func (ps *PushService) SendBroadcastToAllAdmins(payload types.PushPayload) error {
    return ps.sendBroadcast("admin_id IS NOT NULL", payload)
}

// ==================== INTERNAL METHODS ====================

// sendToSubscription sends a push notification to a single subscription
func (ps *PushService) sendToSubscription(subscription models.PushSubscription, payload types.PushPayload) error {
    // Convert payload to JSON
    payloadBytes, err := json.Marshal(payload)
    if err != nil {
        ps.logFailure(subscription, payload, "Failed to marshal payload", 0)
        return fmt.Errorf("failed to marshal payload: %w", err)
    }

    // Create webpush subscription object
    webpushSubscription := &webpush.Subscription{
        Endpoint: subscription.Endpoint,
        Keys: webpush.Keys{
            P256dh: subscription.P256dhKey,
            Auth:   subscription.AuthKey,
        },
    }

    // Send the notification
    resp, err := webpush.SendNotification(payloadBytes, webpushSubscription, &webpush.Options{
        Subscriber:      ps.vapidSubject,
        VAPIDPublicKey:  ps.vapidPublicKey,
        VAPIDPrivateKey: ps.vapidPrivateKey,
        TTL:             2592000, // 30 days in seconds
        Urgency:         webpush.UrgencyHigh,
    })

    if err != nil {
        ps.handleSendError(subscription, payload, err)
        return err
    }
    defer resp.Body.Close()

    // Check response status
    if resp.StatusCode == 201 || resp.StatusCode == 200 {
        // Success
        ps.handleSendSuccess(subscription, payload, resp.StatusCode)
        log.Printf("[PushService] ✅ Notification sent successfully to %s (status: %d)",
            subscription.DeviceName, resp.StatusCode)
        return nil
    }

    // Handle non-success status codes
    if resp.StatusCode == 410 { // Gone - subscription expired
        ps.handleExpiredSubscription(subscription, payload, resp.StatusCode)
        return errors.New("subscription expired (410 Gone)")
    }

    // Other error status codes
    ps.logFailure(subscription, payload, fmt.Sprintf("HTTP %d", resp.StatusCode), resp.StatusCode)
    return fmt.Errorf("push service returned status %d", resp.StatusCode)
}

// handleSendSuccess updates subscription on successful send
func (ps *PushService) handleSendSuccess(subscription models.PushSubscription, payload types.PushPayload, statusCode int) {
    now := time.Now()

    // Reset failure count and update last used
    ps.db.Model(&subscription).Updates(map[string]interface{}{
        "failure_count": 0,
        "last_used_at":  now,
        "updated_at":    now,
    })

    // Log success
    ps.logSuccess(subscription, payload, statusCode)
}

// handleSendError updates subscription on send error
func (ps *PushService) handleSendError(subscription models.PushSubscription, payload types.PushPayload, err error) {
    // Increment failure count
    newFailureCount := subscription.FailureCount + 1

    updates := map[string]interface{}{
        "failure_count": newFailureCount,
        "updated_at":    time.Now(),
    }

    // Deactivate after 3 consecutive failures
    if newFailureCount >= 3 {
        updates["is_active"] = false
        log.Printf("[PushService] ⚠️  Subscription deactivated after 3 failures: %s", subscription.DeviceName)
    }

    ps.db.Model(&subscription).Updates(updates)

    // Log failure
    ps.logFailure(subscription, payload, err.Error(), 0)
}

// handleExpiredSubscription marks subscription as expired
func (ps *PushService) handleExpiredSubscription(subscription models.PushSubscription, payload types.PushPayload, statusCode int) {
    ps.db.Model(&subscription).Updates(map[string]interface{}{
        "is_active":  false,
        "updated_at": time.Now(),
    })

    ps.logFailure(subscription, payload, "Subscription expired (410 Gone)", statusCode)
    log.Printf("[PushService] ⚠️  Subscription expired and deactivated: %s", subscription.DeviceName)
}

// sendBroadcast sends to multiple subscriptions with batching
func (ps *PushService) sendBroadcast(condition string, payload types.PushPayload) error {
    // Fetch all matching active subscriptions
    var subscriptions []models.PushSubscription
    err := ps.db.Where(condition+" AND is_active = ?", true).Find(&subscriptions).Error
    if err != nil {
        return fmt.Errorf("failed to fetch subscriptions: %w", err)
    }

    if len(subscriptions) == 0 {
        log.Printf("[PushService] No active subscriptions for broadcast")
        return nil
    }

    log.Printf("[PushService] Broadcasting to %d devices", len(subscriptions))

    // Send in batches of 100 to avoid overwhelming the system
    batchSize := 100
    for i := 0; i < len(subscriptions); i += batchSize {
        end := i + batchSize
        if end > len(subscriptions) {
            end = len(subscriptions)
        }

        batch := subscriptions[i:end]
        for _, subscription := range batch {
            go ps.sendToSubscription(subscription, payload)
        }

        // Small delay between batches
        if end < len(subscriptions) {
            time.Sleep(100 * time.Millisecond)
        }
    }

    return nil
}

// ==================== LOGGING ====================

// logSuccess logs a successful push notification
func (ps *PushService) logSuccess(subscription models.PushSubscription, payload types.PushPayload, statusCode int) {
    payloadJSON, _ := json.Marshal(payload)

    log := models.PushNotificationLog{
        SubscriptionID: &subscription.ID,
        UserID:         subscription.UserID,
        AdminID:        subscription.AdminID,
        Title:          payload.Title,
        Body:           payload.Body,
        Payload:        payloadJSON,
        Status:         "sent",
        HTTPStatusCode: statusCode,
    }

    ps.db.Create(&log)
}

// logFailure logs a failed push notification
func (ps *PushService) logFailure(subscription models.PushSubscription, payload types.PushPayload, errorMessage string, statusCode int) {
    payloadJSON, _ := json.Marshal(payload)

    status := "failed"
    if statusCode == 410 {
        status = "expired"
    }

    log := models.PushNotificationLog{
        SubscriptionID: &subscription.ID,
        UserID:         subscription.UserID,
        AdminID:        subscription.AdminID,
        Title:          payload.Title,
        Body:           payload.Body,
        Payload:        payloadJSON,
        Status:         status,
        ErrorMessage:   errorMessage,
        HTTPStatusCode: statusCode,
    }

    ps.db.Create(&log)
}

HTTP Controllers

controllers/push_controller.go

package controllers

import (
    "net/http"

    "github.com/gin-gonic/gin"
    "github.com/google/uuid"

    "your-app/services"
    "your-app/types"
    "your-app/utils"
)

// PushController handles HTTP requests for push notifications
type PushController struct {
    pushService *services.PushService
}

// NewPushController creates a new PushController
func NewPushController(pushService *services.PushService) *PushController {
    return &PushController{
        pushService: pushService,
    }
}

// Subscribe handles POST /api/push/subscribe
func (pc *PushController) Subscribe(c *gin.Context) {
    var req types.SubscribePushRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        utils.ErrorResponse(c, http.StatusBadRequest, "Invalid request: "+err.Error())
        return
    }

    // Get user ID from JWT context (set by auth middleware)
    userID, exists := c.Get("userID")
    if !exists {
        utils.ErrorResponse(c, http.StatusUnauthorized, "User not authenticated")
        return
    }

    // Check if it's a regular user or admin
    isAdmin, _ := c.Get("isAdmin")

    var userUUID, adminUUID *uuid.UUID
    parsedUUID, err := uuid.Parse(userID.(string))
    if err != nil {
        utils.ErrorResponse(c, http.StatusBadRequest, "Invalid user ID")
        return
    }

    if isAdmin == true {
        adminUUID = &parsedUUID
    } else {
        userUUID = &parsedUUID
    }

    // Subscribe
    response, err := pc.pushService.Subscribe(userUUID, adminUUID, req)
    if err != nil {
        utils.ErrorResponse(c, http.StatusBadRequest, err.Error())
        return
    }

    utils.SuccessResponse(c, "Subscription successful", response)
}

// Unsubscribe handles POST /api/push/unsubscribe
func (pc *PushController) Unsubscribe(c *gin.Context) {
    var req types.UnsubscribePushRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        utils.ErrorResponse(c, http.StatusBadRequest, "Invalid request: "+err.Error())
        return
    }

    if err := pc.pushService.Unsubscribe(req.Endpoint); err != nil {
        utils.ErrorResponse(c, http.StatusBadRequest, err.Error())
        return
    }

    utils.SuccessResponse(c, "Unsubscribed successfully", types.UnsubscribePushResponse{
        Success: true,
        Message: "Unsubscribed successfully",
    })
}

// GetDevices handles GET /api/push/devices
func (pc *PushController) GetDevices(c *gin.Context) {
    userID, exists := c.Get("userID")
    if !exists {
        utils.ErrorResponse(c, http.StatusUnauthorized, "User not authenticated")
        return
    }

    parsedUUID, err := uuid.Parse(userID.(string))
    if err != nil {
        utils.ErrorResponse(c, http.StatusBadRequest, "Invalid user ID")
        return
    }

    devices, err := pc.pushService.GetUserDevices(parsedUUID)
    if err != nil {
        utils.ErrorResponse(c, http.StatusInternalServerError, "Failed to fetch devices")
        return
    }

    utils.SuccessResponse(c, "Devices fetched successfully", types.GetDevicesResponse{
        Success: true,
        Count:   len(devices),
        Devices: devices,
    })
}

// SendTestNotification handles POST /api/push/test/:userId (admin only)
func (pc *PushController) SendTestNotification(c *gin.Context) {
    userIDStr := c.Param("userId")
    userID, err := uuid.Parse(userIDStr)
    if err != nil {
        utils.ErrorResponse(c, http.StatusBadRequest, "Invalid user ID")
        return
    }

    // Optional: target specific device
    deviceID := c.Query("deviceId")

    payload := types.PushPayload{
        Title: "Test Notification",
        Body:  "This is a test push notification from your backend",
        Tag:   "test",
        URL:   "/",
    }

    if deviceID != "" {
        err = pc.pushService.SendToUserDevice(userID, deviceID, payload)
    } else {
        err = pc.pushService.SendToUser(userID, payload)
    }

    if err != nil {
        utils.ErrorResponse(c, http.StatusInternalServerError, "Failed to send notification")
        return
    }

    utils.SuccessResponse(c, "Test notification sent successfully", gin.H{
        "userId":   userID,
        "deviceId": deviceID,
    })
}

Route Configuration

routes/push_routes.go

package routes

import (
    "github.com/gin-gonic/gin"

    "your-app/controllers"
    "your-app/middleware"
)

// SetupPushRoutes configures push notification routes
func SetupPushRoutes(router *gin.Engine, pushController *controllers.PushController) {
    push := router.Group("/api/push")
    {
        // Public routes (require authentication only)
        push.Use(middleware.AuthMiddleware())
        {
            push.POST("/subscribe", pushController.Subscribe)
            push.POST("/unsubscribe", pushController.Unsubscribe)
            push.GET("/devices", pushController.GetDevices)
        }

        // Admin routes (require admin role)
        push.Use(middleware.AdminMiddleware())
        {
            push.POST("/test/:userId", pushController.SendTestNotification)
        }
    }
}

Middleware

middleware/auth.go

package middleware

import (
    "net/http"
    "strings"

    "github.com/gin-gonic/gin"
    "github.com/golang-jwt/jwt/v5"
    "os"
)

// AuthMiddleware validates JWT tokens
func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        // Get token from Authorization header or cookie
        tokenString := extractToken(c)
        if tokenString == "" {
            c.JSON(http.StatusUnauthorized, gin.H{"error": "No token provided"})
            c.Abort()
            return
        }

        // Parse and validate token
        token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
            return []byte(os.Getenv("JWT_SECRET")), nil
        })

        if err != nil || !token.Valid {
            c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid token"})
            c.Abort()
            return
        }

        // Extract claims
        claims, ok := token.Claims.(jwt.MapClaims)
        if !ok {
            c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid token claims"})
            c.Abort()
            return
        }

        // Set user context
        c.Set("userID", claims["sub"].(string))
        c.Set("isAdmin", claims["isAdmin"])

        c.Next()
    }
}

// AdminMiddleware checks if user is an admin
func AdminMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        isAdmin, exists := c.Get("isAdmin")
        if !exists || isAdmin != true {
            c.JSON(http.StatusForbidden, gin.H{"error": "Admin access required"})
            c.Abort()
            return
        }
        c.Next()
    }
}

// extractToken extracts JWT from Authorization header or cookie
func extractToken(c *gin.Context) string {
    // Try Authorization header first
    authHeader := c.GetHeader("Authorization")
    if authHeader != "" {
        parts := strings.Split(authHeader, " ")
        if len(parts) == 2 && parts[0] == "Bearer" {
            return parts[1]
        }
    }

    // Try cookie
    token, err := c.Cookie("auth-token")
    if err == nil {
        return token
    }

    return ""
}

Utilities

utils/response.go

package utils

import (
    "github.com/gin-gonic/gin"
    "net/http"
)

// SuccessResponse sends a standardized success response
func SuccessResponse(c *gin.Context, message string, data interface{}) {
    c.JSON(http.StatusOK, gin.H{
        "success": true,
        "message": message,
        "data":    data,
    })
}

// ErrorResponse sends a standardized error response
func ErrorResponse(c *gin.Context, statusCode int, message string) {
    c.JSON(statusCode, gin.H{
        "success": false,
        "error":   message,
    })
}

utils/device_detector.go

package utils

import (
    "strings"

    "your-app/types"
)

// ParseUserAgent parses a user agent string and returns device metadata
func ParseUserAgent(userAgent string) types.DeviceMetadata {
    metadata := types.DeviceMetadata{
        DeviceName: "Unknown Device",
        Browser:    "Unknown",
        OS:         "Unknown",
        DeviceType: "desktop", // Default
    }

    if userAgent == "" {
        return metadata
    }

    ua := strings.ToLower(userAgent)

    // Detect Browser
    switch {
    case strings.Contains(ua, "edg/"):
        metadata.Browser = "Edge"
    case strings.Contains(ua, "chrome/") || strings.Contains(ua, "crios/"):
        metadata.Browser = "Chrome"
    case strings.Contains(ua, "firefox/") || strings.Contains(ua, "fxios/"):
        metadata.Browser = "Firefox"
    case strings.Contains(ua, "safari/") && !strings.Contains(ua, "chrome"):
        metadata.Browser = "Safari"
    case strings.Contains(ua, "opera/") || strings.Contains(ua, "opr/"):
        metadata.Browser = "Opera"
    }

    // Detect OS
    switch {
    case strings.Contains(ua, "windows"):
        metadata.OS = "Windows"
    case strings.Contains(ua, "mac os x") || strings.Contains(ua, "macos"):
        metadata.OS = "macOS"
    case strings.Contains(ua, "linux"):
        metadata.OS = "Linux"
    case strings.Contains(ua, "android"):
        metadata.OS = "Android"
    case strings.Contains(ua, "iphone") || strings.Contains(ua, "ipad"):
        metadata.OS = "iOS"
    }

    // Detect Device Type
    switch {
    case strings.Contains(ua, "mobile") || strings.Contains(ua, "android") ||
         strings.Contains(ua, "iphone"):
        metadata.DeviceType = "mobile"
    case strings.Contains(ua, "tablet") || strings.Contains(ua, "ipad"):
        metadata.DeviceType = "tablet"
    default:
        metadata.DeviceType = "desktop"
    }

    // Build device name
    metadata.DeviceName = metadata.Browser + " on " + metadata.OS

    return metadata
}

Main Application

cmd/server/main.go

package main

import (
    "log"
    "os"

    "github.com/gin-contrib/cors"
    "github.com/gin-gonic/gin"
    "github.com/joho/godotenv"
    "gorm.io/driver/postgres"
    "gorm.io/gorm"

    "your-app/controllers"
    "your-app/models"
    "your-app/routes"
    "your-app/services"
)

func main() {
    // Load environment variables
    if err := godotenv.Load(); err != nil {
        log.Println("No .env file found")
    }

    // Connect to database
    db, err := connectDB()
    if err != nil {
        log.Fatalf("Failed to connect to database: %v", err)
    }

    // Run migrations
    if err := runMigrations(db); err != nil {
        log.Fatalf("Failed to run migrations: %v", err)
    }

    // Initialize services
    pushService := services.NewPushService(db)

    // Initialize controllers
    pushController := controllers.NewPushController(pushService)

    // Setup Gin router
    router := gin.Default()

    // CORS middleware
    router.Use(cors.New(cors.Config{
        AllowOrigins:     []string{"http://localhost:3000", "http://localhost:3001"},
        AllowMethods:     []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
        AllowHeaders:     []string{"Origin", "Content-Type", "Authorization"},
        AllowCredentials: true,
    }))

    // Setup routes
    routes.SetupPushRoutes(router, pushController)

    // Health check
    router.GET("/health", func(c *gin.Context) {
        c.JSON(200, gin.H{"status": "ok"})
    })

    // Start server
    port := os.Getenv("PORT")
    if port == "" {
        port = "8080"
    }

    log.Printf("Starting server on port %s", port)
    if err := router.Run(":" + port); err != nil {
        log.Fatalf("Failed to start server: %v", err)
    }
}

func connectDB() (*gorm.DB, error) {
    dsn := os.Getenv("DATABASE_URL")
    if dsn == "" {
        dsn = "host=localhost user=postgres password=postgres dbname=your_app port=5432 sslmode=disable"
    }

    db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})
    if err != nil {
        return nil, err
    }

    log.Println("Database connected successfully")
    return db, nil
}

func runMigrations(db *gorm.DB) error {
    return db.AutoMigrate(
        &models.PushSubscription{},
        &models.PushNotificationLog{},
    )
}

Testing

Basic Testing Example

package services_test

import (
    "testing"

    "github.com/google/uuid"
    "github.com/stretchr/testify/assert"
    "gorm.io/driver/sqlite"
    "gorm.io/gorm"

    "your-app/models"
    "your-app/services"
    "your-app/types"
)

func setupTestDB(t *testing.T) *gorm.DB {
    db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
    if err != nil {
        t.Fatalf("Failed to connect to test database: %v", err)
    }

    // Run migrations
    db.AutoMigrate(&models.PushSubscription{}, &models.PushNotificationLog{})

    return db
}

func TestPushService_Subscribe(t *testing.T) {
    db := setupTestDB(t)
    pushService := services.NewPushService(db)

    userID := uuid.New()
    req := types.SubscribePushRequest{
        Endpoint: "https://fcm.googleapis.com/test-endpoint",
        Keys: types.SubscriptionKeys{
            P256dh: "test-p256dh-key",
            Auth:   "test-auth-key",
        },
        UserAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Chrome/120.0.0.0",
    }

    // Test subscription
    response, err := pushService.Subscribe(&userID, nil, req)

    assert.NoError(t, err)
    assert.True(t, response.Success)
    assert.NotEqual(t, uuid.Nil, response.SubscriptionID)
    assert.Contains(t, response.DeviceName, "Chrome")

    // Verify database
    var subscription models.PushSubscription
    err = db.Where("endpoint = ?", req.Endpoint).First(&subscription).Error
    assert.NoError(t, err)
    assert.Equal(t, userID, *subscription.UserID)
    assert.True(t, subscription.IsActive)
}

func TestPushService_DeviceLimit(t *testing.T) {
    db := setupTestDB(t)
    pushService := services.NewPushService(db)

    userID := uuid.New()

    // Create 5 subscriptions (limit)
    for i := 0; i < 5; i++ {
        req := types.SubscribePushRequest{
            Endpoint: fmt.Sprintf("https://fcm.googleapis.com/endpoint-%d", i),
            Keys: types.SubscriptionKeys{
                P256dh: "test-key",
                Auth:   "test-auth",
            },
        }
        _, err := pushService.Subscribe(&userID, nil, req)
        assert.NoError(t, err)
    }

    // Try to create 6th subscription (should fail)
    req := types.SubscribePushRequest{
        Endpoint: "https://fcm.googleapis.com/endpoint-6",
        Keys: types.SubscriptionKeys{
            P256dh: "test-key",
            Auth:   "test-auth",
        },
    }
    _, err := pushService.Subscribe(&userID, nil, req)
    assert.Error(t, err)
    assert.Contains(t, err.Error(), "device limit reached")
}

Next Steps

✅ Backend implementation complete!

Now proceed to:

➡️ Part 3: Frontend Implementation (Next.js)

Part 3 will cover:

Next.js API routes (SSR forwarding)
PushNotificationManager component
usePushNotifications hook
TypeScript type definitions
Complete frontend integration

Summary

You now have a complete, production-ready backend for push notifications with:

✅ GORM models with health tracking
✅ Non-blocking goroutine-based sending
✅ Multi-device support (up to 5 devices)
✅ Automatic failure handling and deactivation
✅ Complete audit logging
✅ Advanced targeting (user, admin, broadcast)
✅ RESTful API with JWT authentication
✅ Device metadata detection
✅ Comprehensive error handling

The backend can handle thousands of simultaneous push notifications efficiently using goroutines.

# Self-Hosted Push Notifications Part-1

Bipin C — Wed, 22 Oct 2025 11:46:19 +0000

Self-Hosted Push Notifications Specification

Part 1: Architecture & Setup Overview

Version: 1.0
Last Updated: October 2025
Author: Bunty9
License: MIT (Free to use and adapt)

Quick Links for all Posts

Part	Title	Topics Covered
Part 1	Architecture & Setup	System overview, VAPID, database schema, project structure
Part 2	Backend Implementation	GORM models, PushService, controllers, routes, middleware
Part 3	Frontend Implementation	API routes, hooks, components, TypeScript types
Part 4	Service Worker & PWA	SW implementation, PWA manifest, action handlers, offline
Part 5	Advanced & Deployment	Targeting, scheduling, rate limiting, Docker, Kubernetes
Part 6	Monitoring & Debugging	Metrics, logging, profiling, health checks, alerting
Part 7	Best Practices & Security	Security, VAPID management, validation, optimization, testing
Part 8	Reference & FAQ	API reference, browser compatibility, FAQ, troubleshooting

Introduction
System Overview
Architecture Components
Technology Stack
Prerequisites
VAPID Key Generation
Database Schema Design
Project Structure
Configuration Setup
Next Steps

Introduction

What This Specification Covers

This is a complete, production-ready specification for implementing a self-hosted Web Push notification system without relying on third-party services like Firebase Cloud Messaging (FCM), OneSignal, Pusher, or similar platforms.

Why Self-Hosted Push Notifications?

Advantages:

✅ Full Control - No vendor lock-in, complete customization
✅ Zero Cost - No per-message pricing or monthly fees
✅ Privacy - User data never leaves your infrastructure
✅ Unlimited Scale - No artificial limits or quotas
✅ Custom Logic - Advanced targeting, retry strategies, analytics

Trade-offs:

⚠️ Infrastructure Responsibility - You manage the push gateway
⚠️ Browser Limitations - Safari has limited support on iOS
⚠️ Maintenance - Updates, monitoring, and debugging are your responsibility

Use Cases

This specification is ideal for:

SaaS Platforms - User dashboards, admin panels
Booking Systems - Reservations, confirmations, reminders
E-commerce - Order updates, delivery notifications
Project Management - Task assignments, status updates
Internal Tools - Employee dashboards, admin notifications
Any web application requiring real-time notifications

What You'll Build

By following this specification, you'll implement:

Backend Push Service (Go)
- VAPID-authenticated push gateway
- Multi-device subscription management
- Non-blocking goroutine-based sending
- Advanced targeting strategies
- Automatic failure handling and retry logic
- Complete audit logging
Frontend Integration (Next.js)
- Service worker with background push handling
- PWA configuration for installability
- Subscription management UI
- SSR API routes for secure backend communication
- Type-safe payload structures
Production Features
- Multi-device support (up to 5 devices per user)
- Targeted delivery (individual, role-based, broadcast)
- Rich notifications (actions, images, sounds)
- Offline support (notifications when app is closed)
- Analytics and delivery tracking

System Overview

Web Push Protocol (RFC 8030)

Web Push is a browser standard that enables servers to send messages to web applications via push services. The flow works as follows:

┌──────────────┐        ┌──────────────┐        ┌──────────────┐        ┌──────────────┐
│              │        │              │        │              │        │              │
│   Backend    │───────▶│   Browser    │───────▶│ Push Service │───────▶│   User's     │
│   Server     │ VAPID  │   Endpoint   │ RFC    │ (Google/     │ Push   │   Browser    │
│   (Go)       │ Auth   │   (HTTPS)    │ 8030   │  Mozilla)    │ Event  │   (Client)   │
│              │        │              │        │              │        │              │
└──────────────┘        └──────────────┘        └──────────────┘        └──────────────┘
     Step 1                  Step 2                  Step 3                  Step 4

Step 1: Your Go backend creates a signed payload with VAPID authentication
Step 2: Backend sends encrypted payload to browser's push endpoint (provided during subscription)
Step 3: Browser's push service (Google FCM for Chrome, Mozilla Push for Firefox) validates signature
Step 4: Push service delivers notification to user's browser, triggering service worker

VAPID (RFC 8292)

VAPID = Voluntary Application Server Identification

VAPID is the authentication mechanism that proves you own the application sending push notifications. It uses asymmetric cryptography (public/private key pairs):

Public Key - Shared with browsers during subscription (safe to expose)
Private Key - Used to sign push messages (keep secret)
Subject - Contact email (usually mailto:admin@yourdomain.com)

Why VAPID?

Prevents unauthorized parties from sending notifications
Allows push services to contact you if there's abuse
Required by modern browsers (Chrome 52+, Firefox 46+)

Architecture Diagram

Architecture Components

1. Backend Service (Go)

Responsibilities:

Generate and manage VAPID keys
Store and manage push subscriptions
Send push notifications via Web Push protocol
Handle delivery failures and retry logic
Log all notification events
Provide subscription management APIs

Key Libraries:

github.com/SherClockHolmes/webpush-go v1.3.0 - Web Push Protocol implementation
github.com/gin-gonic/gin - HTTP framework
gorm.io/gorm - ORM for database operations
Standard library: crypto/ecdsa, encoding/json

2. Frontend Application (Next.js)

Responsibilities:

Request notification permissions from users
Register service worker for background handling
Subscribe to push notifications via Push API
Display notification UI/badges
Handle notification clicks and actions
Manage subscription lifecycle

Key Technologies:

Next.js 13+ (Pages Router or App Router)
Service Worker API (navigator.serviceWorker)
Push API (PushManager, PushSubscription)
Notification API (Notification, ServiceWorkerRegistration.showNotification)

3. Service Worker

Responsibilities:

Listen for push events (even when app is closed)
Display notifications with custom UI
Handle notification clicks and actions
Manage notification lifecycle (show, close, replace)
Optional: Background sync, caching

Lifecycle:

Install → Activate → Idle → (Push Event) → Active → Idle
                       ▲──────────────────────┘

4. Database

Tables Required:

push_subscriptions - Stores device subscriptions
- User/Admin identification
- Endpoint URL (browser push service)
- Encryption keys (p256dh, auth)
- Device metadata (browser, OS, device name)
- Health tracking (failure_count, is_active)
push_notification_logs - Audit trail
- Notification content
- Delivery status (sent, failed, expired)
- Timestamps and error messages
notifications (Optional) - Persistent notification storage
- For in-app notification center
- Read/unread state
- Archive/delete functionality

Technology Stack

Backend Requirements

Component	Technology	Version	Purpose
Language	Go	1.21+	Backend service
HTTP Framework	Gin	1.9+	REST API endpoints
ORM	GORM	1.25+	Database operations
Database	PostgreSQL	14+	Data persistence
Push Library	webpush-go	1.3.0	Web Push Protocol
Auth	JWT	-	User authentication

Frontend Requirements

Component	Technology	Version	Purpose
Framework	Next.js	13+	React application
Language	TypeScript	5+	Type safety
Service Worker	Workbox (optional)	7+	SW management
PWA	next-pwa (optional)	5+	PWA configuration

Browser Compatibility

Browser	Desktop	Mobile	Notes
Chrome	✅ 52+	✅ 52+	Full support
Firefox	✅ 46+	✅ 46+	Full support
Edge	✅ 79+	✅ 79+	Full support (Chromium-based)
Safari	✅ 16+	⚠️ Limited	iOS requires PWA installation first
Opera	✅ 39+	✅ 39+	Full support (Chromium-based)

Important Safari Notes:

iOS Safari requires the app to be added to home screen (PWA)
No support for push notifications in regular mobile Safari browser
macOS Safari 16+ supports push notifications
Represents ~30% of users, consider fallback strategies

Prerequisites

Developer Skills Required

✅ Go Programming - Intermediate level (goroutines, channels, error handling)
✅ Next.js/React - Intermediate level (hooks, SSR/API routes)
✅ TypeScript - Basic to intermediate
✅ PostgreSQL - Basic (schema design, queries)
✅ REST APIs - Understanding of HTTP methods, status codes
✅ Web APIs - Service Workers, Push API, Notification API
✅ Async JavaScript - Promises, async/await

Infrastructure Requirements

Development Environment:

- Go 1.21+ installed
- Node.js 18+ and npm/yarn
- PostgreSQL 14+ database
- Modern browser (Chrome/Firefox recommended)
- Code editor (VS Code recommended)
- Git for version control

Production Environment:

- HTTPS domain (required for service workers)
- SSL certificate
- Container orchestration (Docker, Kubernetes) or VM
- PostgreSQL database (managed or self-hosted)
- Monitoring/logging solution
- Backup strategy

Environment Setup Checklist

# 1. Check Go installation
go version  # Should be 1.21+

# 2. Check Node.js installation
node --version  # Should be 18+
npm --version

# 3. Check PostgreSQL installation
psql --version  # Should be 14+

# 4. Create project directory
mkdir my-push-notification-app
cd my-push-notification-app

# 5. Initialize Go module
mkdir backend
cd backend
go mod init github.com/yourusername/your-app

# 6. Initialize Next.js app
cd ..
npx create-next-app@latest frontend --typescript

# 7. Create PostgreSQL database
createdb your_app_db

VAPID Key Generation

What Are VAPID Keys?

VAPID keys are ECDSA P-256 key pairs used to authenticate your server when sending push notifications. They prove that notifications are coming from your legitimate server.

Option 1: Generate with web-push CLI (Node.js)

Installation:

npm install -g web-push

Generate Keys:

web-push generate-vapid-keys

Output:

=======================================
Public Key:
BOzzMgOMwVyuziwHiI8Aw9sjs2jcxxC9ivxAGz2Qsue-Vty4lpqRDl6MWvGxJ5UTiNLrkYjHBYSKJCv4NYF1_0c

Private Key:
BNw7fc1ayj3-Az-OJ8DrOj3EDAHCORwO_r3SsrpwkzQ
=======================================

Option 2: Generate with Go Script

Create generate_vapid.go:

package main

import (
    "fmt"
    "log"

    "github.com/SherClockHolmes/webpush-go"
)

func main() {
    privateKey, publicKey, err := webpush.GenerateVAPIDKeys()
    if err != nil {
        log.Fatalf("Failed to generate VAPID keys: %v", err)
    }

    fmt.Println("=======================================")
    fmt.Printf("Public Key:\n%s\n\n", publicKey)
    fmt.Printf("Private Key:\n%s\n", privateKey)
    fmt.Println("=======================================")
    fmt.Println("\nSave these keys securely!")
    fmt.Println("Public key: Add to frontend environment variables")
    fmt.Println("Private key: Add to backend environment variables (KEEP SECRET!)")
}

Run:

# Install dependency
go get github.com/SherClockHolmes/webpush-go

# Generate keys
go run generate_vapid.go

Storing VAPID Keys

Backend (.env or environment variables):

# REQUIRED: Keep private key secret!
VAPID_PRIVATE_KEY=BNw7fc1ayj3-Az-OJ8DrOj3EDAHCORwO_r3SsrpwkzQ
VAPID_PUBLIC_KEY=BOzzMgOMwVyuziwHiI8Aw9sjs2jcxxC9ivxAGz2Qsue-Vty4lpqRDl6MWvGxJ5UTiNLrkYjHBYSKJCv4NYF1_0c
VAPID_SUBJECT=mailto:admin@yourdomain.com  # Your contact email

Frontend (.env.local):

# Safe to expose - used by browsers for subscription
NEXT_PUBLIC_VAPID_PUBLIC_KEY=BOzzMgOMwVyuziwHiI8Aw9sjs2jcxxC9ivxAGz2Qsue-Vty4lpqRDl6MWvGxJ5UTiNLrkYjHBYSKJCv4NYF1_0c

Production Secrets (Kubernetes):

# Create secret
kubectl create secret generic vapid-keys \
  --from-literal=public-key='BOzzMgOMw...' \
  --from-literal=private-key='BNw7fc1ayj...' \
  --from-literal=subject='mailto:admin@yourdomain.com' \
  --namespace=your-namespace

# Reference in deployment
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: backend
    env:
    - name: VAPID_PRIVATE_KEY
      valueFrom:
        secretKeyRef:
          name: vapid-keys
          key: private-key

Key Security Best Practices

✅ Never commit private keys to git

   # Add to .gitignore
   .env
   .env.local
   .env.production

✅ Use different keys for dev/staging/production
✅ Rotate keys periodically (every 6-12 months)
- Generate new keys
- Update backend/frontend env vars
- Users will need to resubscribe (acceptable)
✅ Monitor for key compromise
- Watch for unexpected push volume
- Log all push operations
- Alert on anomalies

Database Schema Design

Table 1: push_subscriptions

Purpose: Store push subscription details for each user device.

CREATE TABLE push_subscriptions (
    -- Primary Identification
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

    -- User/Admin Association (mutually exclusive)
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    admin_id UUID REFERENCES admins(id) ON DELETE CASCADE,

    -- Push Subscription Data (from browser)
    endpoint TEXT NOT NULL,  -- Browser push service URL (unique per device)
    p256dh_key TEXT NOT NULL,  -- Public key for encryption
    auth_key TEXT NOT NULL,    -- Authentication secret

    -- Device Metadata (for multi-device support)
    device_id VARCHAR(255),  -- Stable device identifier
    device_name VARCHAR(255),  -- Human-readable: "Chrome on MacBook Pro"
    device_type VARCHAR(50),   -- mobile, desktop, tablet
    browser VARCHAR(50),       -- Chrome, Firefox, Safari, Edge
    os VARCHAR(50),            -- Windows, macOS, Linux, Android, iOS
    user_agent TEXT,           -- Full user agent string

    -- Health & Lifecycle
    is_active BOOLEAN DEFAULT TRUE,
    failure_count INTEGER DEFAULT 0,  -- Increments on send failure
    last_used_at TIMESTAMP,           -- Last successful push

    -- Timestamps
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),

    -- Constraints
    CONSTRAINT check_user_or_admin CHECK (
        (user_id IS NOT NULL AND admin_id IS NULL) OR
        (user_id IS NULL AND admin_id IS NOT NULL)
    )
);

-- Indexes for Performance
CREATE INDEX idx_push_subscriptions_user_id ON push_subscriptions(user_id);
CREATE INDEX idx_push_subscriptions_admin_id ON push_subscriptions(admin_id);
CREATE INDEX idx_push_subscriptions_is_active ON push_subscriptions(is_active);
CREATE INDEX idx_push_subscriptions_endpoint ON push_subscriptions(endpoint);
CREATE INDEX idx_push_subscriptions_device_id ON push_subscriptions(device_id);
CREATE INDEX idx_push_subscriptions_last_used ON push_subscriptions(last_used_at);

-- Composite index for querying active subscriptions by user
CREATE INDEX idx_push_subscriptions_user_active
ON push_subscriptions(user_id, is_active)
WHERE is_active = TRUE;

-- Unique constraint on endpoint (one subscription per browser endpoint)
CREATE UNIQUE INDEX idx_push_subscriptions_endpoint_unique
ON push_subscriptions(endpoint);

Table 2: push_notification_logs

Purpose: Audit trail for all push notification attempts.

CREATE TABLE push_notification_logs (
    -- Primary Identification
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

    -- Relations
    subscription_id UUID REFERENCES push_subscriptions(id) ON DELETE SET NULL,
    user_id UUID,  -- Denormalized for faster querying
    admin_id UUID,

    -- Notification Content
    title VARCHAR(255),
    body TEXT,
    payload JSONB,  -- Full notification payload

    -- Delivery Status
    status VARCHAR(50) NOT NULL,  -- sent, failed, expired
    error_message TEXT,           -- Populated on failure
    http_status_code INTEGER,     -- Push service response code

    -- Timestamps
    sent_at TIMESTAMP DEFAULT NOW(),
    created_at TIMESTAMP DEFAULT NOW()
);

-- Indexes for Analytics
CREATE INDEX idx_push_notification_logs_subscription_id
ON push_notification_logs(subscription_id);

CREATE INDEX idx_push_notification_logs_status
ON push_notification_logs(status);

CREATE INDEX idx_push_notification_logs_sent_at
ON push_notification_logs(sent_at DESC);

CREATE INDEX idx_push_notification_logs_user_id
ON push_notification_logs(user_id);

-- Composite index for user-specific logs
CREATE INDEX idx_push_notification_logs_user_sent
ON push_notification_logs(user_id, sent_at DESC);

Table 3: notifications (Optional)

Purpose: Persistent in-app notification storage (notification center).

CREATE TABLE notifications (
    -- Primary Identification
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

    -- User/Admin Association
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    admin_id UUID REFERENCES admins(id) ON DELETE CASCADE,

    -- Relations (optional, for filtering)
    booking_id UUID REFERENCES bookings(id) ON DELETE SET NULL,
    order_id UUID REFERENCES orders(id) ON DELETE SET NULL,
    -- Add other relations as needed

    -- Notification Content
    type VARCHAR(100) NOT NULL,  -- booking_confirmed, payment_received, etc.
    title VARCHAR(255) NOT NULL,
    message TEXT NOT NULL,
    data JSONB,  -- Additional contextual data

    -- UI Metadata
    read BOOLEAN DEFAULT FALSE,
    action_url TEXT,  -- Where to navigate on click
    priority VARCHAR(20) DEFAULT 'normal',  -- low, normal, high, urgent

    -- Timestamps
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    deleted_at TIMESTAMP  -- Soft delete
);

-- Indexes for Notification Center
CREATE INDEX idx_notifications_user_id ON notifications(user_id);
CREATE INDEX idx_notifications_admin_id ON notifications(admin_id);
CREATE INDEX idx_notifications_type ON notifications(type);
CREATE INDEX idx_notifications_read ON notifications(read);
CREATE INDEX idx_notifications_created_at ON notifications(created_at DESC);

-- Composite index for unread notifications
CREATE INDEX idx_notifications_user_unread
ON notifications(user_id, read, created_at DESC)
WHERE read = FALSE AND deleted_at IS NULL;

Migration Scripts

Create Migration File: 001_create_push_subscriptions.sql

-- Up Migration
BEGIN;

CREATE TABLE IF NOT EXISTS push_subscriptions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    admin_id UUID REFERENCES admins(id) ON DELETE CASCADE,
    endpoint TEXT NOT NULL,
    p256dh_key TEXT NOT NULL,
    auth_key TEXT NOT NULL,
    device_id VARCHAR(255),
    device_name VARCHAR(255),
    device_type VARCHAR(50),
    browser VARCHAR(50),
    os VARCHAR(50),
    user_agent TEXT,
    is_active BOOLEAN DEFAULT TRUE,
    failure_count INTEGER DEFAULT 0,
    last_used_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    CONSTRAINT check_user_or_admin CHECK (
        (user_id IS NOT NULL AND admin_id IS NULL) OR
        (user_id IS NULL AND admin_id IS NOT NULL)
    )
);

CREATE INDEX idx_push_subscriptions_user_id ON push_subscriptions(user_id);
CREATE INDEX idx_push_subscriptions_admin_id ON push_subscriptions(admin_id);
CREATE INDEX idx_push_subscriptions_is_active ON push_subscriptions(is_active);
CREATE UNIQUE INDEX idx_push_subscriptions_endpoint_unique ON push_subscriptions(endpoint);

COMMIT;

-- Down Migration
BEGIN;
DROP TABLE IF EXISTS push_subscriptions CASCADE;
COMMIT;

Apply Migration:

# Using psql
psql -U your_user -d your_database -f 001_create_push_subscriptions.sql

# Using GORM AutoMigrate (alternative)
db.AutoMigrate(&models.PushSubscription{})

Project Structure

Recommended Backend Structure (Go)

backend/
├── cmd/
│   └── server/
│       └── main.go                    # Entry point
├── config/
│   ├── database.go                    # DB connection
│   └── vapid.go                       # VAPID key loading
├── models/
│   ├── push_subscription.go           # GORM model
│   └── push_notification_log.go       # Logging model
├── services/
│   └── push_service.go                # Core push logic
├── controllers/
│   └── push_controller.go             # HTTP handlers
├── routes/
│   └── push_routes.go                 # Route definitions
├── middleware/
│   └── auth.go                        # JWT validation
├── types/
│   └── push_types.go                  # Request/response types
├── utils/
│   ├── response.go                    # HTTP response helpers
│   └── device_detector.go             # Parse user agents
├── .env                               # Environment variables
├── go.mod                             # Go dependencies
└── go.sum

Recommended Frontend Structure (Next.js)

frontend/
├── public/
│   ├── sw.js                          # Service worker (manual)
│   ├── manifest.json                  # PWA manifest
│   ├── icon-192x192.png               # PWA icons
│   └── icon-512x512.png
├── pages/
│   ├── _app.tsx                       # App wrapper
│   ├── _document.tsx                  # HTML document
│   ├── index.tsx                      # Home page
│   └── api/
│       └── push/
│           ├── subscribe.ts           # POST /api/push/subscribe
│           ├── unsubscribe.ts         # POST /api/push/unsubscribe
│           └── devices.ts             # GET /api/push/devices
├── components/
│   └── PushNotificationManager.tsx    # Subscription UI
├── hooks/
│   └── usePushNotifications.ts        # Push logic hook
├── types/
│   └── push.ts                        # TypeScript types
├── utils/
│   └── push-utils.ts                  # Helper functions
├── .env.local                         # Environment variables
├── next.config.js                     # Next.js config
├── package.json
└── tsconfig.json

Configuration Setup

Backend Environment Variables

Create .env file:

# Server Configuration
PORT=8080
HOST=0.0.0.0
ENV=development  # development, staging, production

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_USER=your_user
DB_PASSWORD=your_password
DB_NAME=your_database
DB_SSLMODE=disable  # Use 'require' in production

# VAPID Configuration (generated earlier)
VAPID_PUBLIC_KEY=BOzzMgOMwVyuziwHiI8Aw9sjs2jcxxC9ivxAGz2Qsue-Vty4lpqRDl6MWvGxJ5UTiNLrkYjHBYSKJCv4NYF1_0c
VAPID_PRIVATE_KEY=BNw7fc1ayj3-Az-OJ8DrOj3EDAHCORwO_r3SsrpwkzQ
VAPID_SUBJECT=mailto:admin@yourdomain.com

# JWT Configuration (for authentication)
JWT_SECRET=your-jwt-secret-key-min-32-chars
JWT_EXPIRY=24h

# Rate Limiting (optional)
RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=1m

# Logging
LOG_LEVEL=info  # debug, info, warn, error

Loading Configuration in Go:

package config

import (
    "fmt"
    "log"
    "os"

    "github.com/joho/godotenv"
)

type Config struct {
    Port           string
    DatabaseURL    string
    VAPIDPublicKey string
    VAPIDPrivateKey string
    VAPIDSubject   string
    JWTSecret      string
}

func Load() (*Config, error) {
    // Load .env file in development
    if os.Getenv("ENV") != "production" {
        if err := godotenv.Load(); err != nil {
            log.Println("No .env file found")
        }
    }

    config := &Config{
        Port: getEnv("PORT", "8080"),
        DatabaseURL: fmt.Sprintf(
            "host=%s port=%s user=%s password=%s dbname=%s sslmode=%s",
            getEnv("DB_HOST", "localhost"),
            getEnv("DB_PORT", "5432"),
            os.Getenv("DB_USER"),
            os.Getenv("DB_PASSWORD"),
            os.Getenv("DB_NAME"),
            getEnv("DB_SSLMODE", "disable"),
        ),
        VAPIDPublicKey: os.Getenv("VAPID_PUBLIC_KEY"),
        VAPIDPrivateKey: os.Getenv("VAPID_PRIVATE_KEY"),
        VAPIDSubject: os.Getenv("VAPID_SUBJECT"),
        JWTSecret: os.Getenv("JWT_SECRET"),
    }

    // Validate required configs
    if config.VAPIDPublicKey == "" || config.VAPIDPrivateKey == "" {
        return nil, fmt.Errorf("VAPID keys are required")
    }

    return config, nil
}

func getEnv(key, fallback string) string {
    if value := os.Getenv(key); value != "" {
        return value
    }
    return fallback
}

Frontend Environment Variables

Create .env.local file:

# Backend API URL
NEXT_PUBLIC_API_URL=http://localhost:8080

# VAPID Public Key (same as backend)
NEXT_PUBLIC_VAPID_PUBLIC_KEY=BOzzMgOMwVyuziwHiI8Aw9sjs2jcxxC9ivxAGz2Qsue-Vty4lpqRDl6MWvGxJ5UTiNLrkYjHBYSKJCv4NYF1_0c

# Feature Flags (optional)
NEXT_PUBLIC_ENABLE_PUSH_NOTIFICATIONS=true

Using Environment Variables in Next.js:

// utils/config.ts
export const config = {
    apiUrl: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8080',
    vapidPublicKey: process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY || '',
    enablePushNotifications: process.env.NEXT_PUBLIC_ENABLE_PUSH_NOTIFICATIONS === 'true',
};

// Validate on build
if (!config.vapidPublicKey) {
    throw new Error('NEXT_PUBLIC_VAPID_PUBLIC_KEY is required');
}

Next Steps

Now that you understand the architecture and have completed the initial setup, proceed to:

➡️ Part 2: Backend Implementation (Go)

Part 2 will cover:

GORM models for push subscriptions
Push service implementation with webpush-go
Non-blocking goroutine-based sending
Multi-device subscription management
Advanced targeting strategies
Error handling and automatic deactivation
HTTP controllers and routes
Complete code examples

DEV Community: Bipin C

Safe Remote Server Reboot Guide

For Ubuntu Desktop with Docker and Cloudflare Tunnel

Prerequisites

Pre-Reboot Checklist

1. Check Docker Starts on Boot

2. Check SSH Starts on Boot

3. Check Container Restart Policies

4. (Ubuntu Desktop Only) Configure Auto-Login

Quick Verification Script

Safe to Reboot Checklist

Reboot Procedure

Step 1: Reboot the Server

Step 2: Wait

Step 3: Reconnect

Step 4: Verify

Troubleshooting

Can't reconnect after 5 minutes

Preventive Test (Optional)

Docker User Permissions

Summary

Multi-Instance n8n Self-Hosting Guide

Docker, PostgreSQL, and Cloudflare Zero Trust Tunnels

Prerequisites: Remote Server Access

Setup your SSH server access

Table of Contents

1. Architecture Overview

System Architecture

Key Design Principles

2. Tunnel Strategy

3. Ubuntu Desktop Server Preparation

3.1 Disable Sleep/Suspend (If Ubuntu Desktop)

3.2 Verify Docker Installation

4. Create n8n Tunnel in Cloudflare

5. Directory and File Setup

5.1 Create Project Directory

5.2 Create .gitignore

5.3 Directory Structure

6. Environment Variables Configuration

6.1 Generate Secure Values

6.2 Create Environment File

6.3 Secure the File

6.4 Critical Warnings

7. Docker Compose Configuration

7.1 Configuration Differences: Prod vs Dev

8. Configure Public Hostnames

Production Hostname

Development Hostname

Understanding Service URLs

9. Securing the Development Instance

9.1 Create Access Application

9.2 Create Access Policy

9.3 Configure Webhook Bypass

Create a Separate Webhook Application

Add Bypass Policy

How It Works

10. Deployment

10.1 Validate Configuration

10.2 Start Services

10.3 Monitor Startup

10.4 Verify All Containers Running

11. First-Time n8n Setup

11.1 Production Instance

11.2 Development Instance

12. Verification and Testing

12.1 Test Container Health

12.2 Test Tunnel Connectivity

12.3 Test Database Connectivity

12.4 Test Webhooks

13. Backup Procedures

13.1 Manual Backup

13.2 Automated Backup Script

13.3 Schedule Daily Backups

13.4 Restore from Backup

14. Troubleshooting

Common Issues

Useful Commands

Network Debugging

15. Quick Reference

Your Endpoints