Realtime Backend Service Example

This example demonstrates using Volcano Realtime with a service role key for backend/server-to-server communication.

Realtime Backend Service Example

This example demonstrates using Volcano Realtime with a service role key for backend/server-to-server communication.

Use Cases

Admin notifications - Broadcast system messages to all connected users
Status updates - Send server health, deployment status, etc.
Background jobs - Push progress updates for long-running tasks
Bots/Automation - Automated messages without user authentication

Quick Start

# Install dependencies
yarn install

# Create .env file
echo "SERVICE_KEY=sk-your-service-key-here" > .env

# Run the service
yarn dev

Authentication

Service role keys contain the project ID, so the anon key is optional:

// Simplest: service key only
const realtime = new VolcanoRealtime({
  apiUrl: 'https://api.yourapp.com',
  anonKey: '',                    // Not required
  accessToken: 'sk-your-key'      // Service role key
});

// With extra validation
const realtime = new VolcanoRealtime({
  apiUrl: 'https://api.yourapp.com',
  anonKey: 'your-anon-key',       // Must match service key project
  accessToken: 'sk-your-key'
});

Setup

Install dependencies:

yarn install

Create a .env file:

# Required: Your service role key
SERVICE_KEY=sk-your-service-key-here

# Optional: Volcano API URL (defaults to http://localhost:8000)
VOLCANO_API_URL=http://localhost:8000

# Optional: Anon key for additional validation
ANON_KEY=ak-your-anon-key

Run the service:

yarn dev

How It Works

The service:

Connects to Volcano Realtime using the service key
Subscribes to the admin-notifications channel
Sends a welcome message
Sends periodic heartbeat messages every 10 seconds
Logs any received events

Security Notes

Never expose service keys in client-side code
Service keys bypass Row Level Security for Postgres changes
Service keys should only be used in trusted backend environments
If the service key is compromised, regenerate it immediately
Store service keys in environment variables or secure secret management

Frontend Client Example

Frontend clients can listen to the same channels using user tokens:

const realtime = new VolcanoRealtime({
  apiUrl: 'https://api.yourapp.com',
  anonKey: anonKey,
  accessToken: userToken
});

const channel = realtime.channel('admin-notifications');
channel.on('status_update', (payload) => {
  console.log('Server status:', payload.status);
});
await channel.subscribe();

Both backend (service key) and frontend (user token) clients can communicate on the same channels within a project.

Project Structure

realtime-backend-service/
├── package.json    # Dependencies
├── index.js        # Service logic
├── .env            # Configuration (create this)
└── README.md

Realtime Backend Service Example

On this page