Complete step-by-step guide to get started with the Erebus platform, from sign-up to your first real-time connection.

Getting Started with Erebus Platform

This guide will walk you through everything you need to start building real-time applications with Erebus, from creating your account to making your first WebSocket connection.

Prerequisites

Before getting started, make sure you have:

A GitHub account (required for authentication)
A modern web browser
Basic familiarity with JavaScript/TypeScript
A project where you want to add real-time features

[Screenshot placeholder: Sign-in page with GitHub button]

Navigate to erebus.sh
Click "Sign in with GitHub"
Authorize Erebus to access your GitHub account
You'll be redirected to the platform dashboard

The Erebus platform uses GitHub OAuth for secure authentication. This ensures we never store your passwords and provides seamless access management.

Step 2: Choose Your Plan

[Screenshot placeholder: Pricing page with plan selection]

After signing in, you'll need to select a subscription plan:

Review the available pricing tiers
Select the plan that fits your usage needs
Complete the subscription process
You'll be redirected to create your first project

Free Tier Available

Most plans include generous free usage limits, perfect for development and small applications.

Step 3: Create Your First Project

[Screenshot placeholder: Create project dialog with form fields]

Projects organize your real-time applications and provide isolated environments for different use cases.

Creating the Project

Click "Create new project" from your dashboard
Enter a descriptive project name (3-100 characters)
Choose your deployment region:
- Global: Automatically routes to the closest region (recommended)
- EU: Fixed deployment in European data centers (coming soon)
Click "Create Project"

Project Organization

Each project provides:

Isolated API keys and authentication
Separate analytics and monitoring
Independent audit logs
Project-specific settings and webhooks

Project Limits

You can create up to 50 projects per account. Each project can have unlimited API keys.

Step 4: Generate Your First API Key

[Screenshot placeholder: API Keys page with create dialog]

API keys authenticate your applications and control access to your real-time infrastructure.

Creating an API Key

Navigate to the "API Keys" section in your project
Click "Create new key"
Enter a descriptive label (e.g., "Development Key")
Choose your environment:
- Development: For testing and development work
- Production: For live applications

Environment Types

Currently, development and production keys have the same capabilities. The separation exists for organization and security best practices.

API Key Format

Your API keys follow this format:

Production: sk-er-[random-string]
Development: dv-er-[random-string]

Important: Copy your API key immediately after creation. You won't be able to see the full key again for security reasons.

Step 5: Explore the Project Dashboard

[Screenshot placeholder: Project dashboard with navigation sidebar]

Your project dashboard provides access to all platform features:

Dashboard: Analytics overview with connection metrics
Usage: Detailed usage analytics and time-range selection
API Keys: Manage authentication keys and permissions
Audit Logs: Security and activity tracking
Settings: Project configuration and webhooks
WebSocket Inspector: Real-time connection debugging (coming soon)

Dashboard Metrics

The main dashboard shows:

Total connections over time
Message volume and subscription counts
Peak usage statistics
Real-time activity graphs

Step 6: Configure Project Settings

[Screenshot placeholder: Project settings page with webhook configuration]

Basic Settings

Navigate to "Settings" in your project
Configure your project name and description
Set up webhook URLs for message forwarding (optional)

Webhook Configuration

Webhooks allow you to forward messages to your backend services:

Enter a valid HTTPS base URL (e.g., https://yourapi.com)
The system validates the URL format automatically
Messages will be forwarded to [webhook-url]/erebus/webhook

Webhook Requirements

Webhook URLs must use HTTPS and be base URLs without paths. The system automatically appends /erebus/webhook to your configured URL.

Step 7: Make Your First Connection

Now let's connect to your Erebus project using the SDK:

Install the SDK

npm install @erebus-sh/sdk

Basic Connection Example

import { ErebusClient, ErebusClientState } from "@erebus-sh/sdk/client";

// Initialize the client
const client = ErebusClient.createClient({
  client: ErebusClientState.PubSub,
  authBaseUrl: "YOUR_AUTH_SERVER_URL" // Your backend auth endpoint
});

// Join a channel (this creates the channel if it doesn't exist)
client.joinChannel("my-first-channel");

// Connect to Erebus
await client.connect();

// Subscribe to messages
await client.subscribe("notifications", (message) => {
  console.log("📩 Received message:", message.payload);
});

// Publish a test message
await client.publish("notifications", {
  type: "welcome",
  message: "Hello from Erebus! 🚀"
});

console.log("✅ Successfully connected to Erebus!");

Authentication Server Setup

You'll need an authentication endpoint that returns JWT tokens. Here's a minimal Express.js example:

// auth-server.js
const express = require('express');
const jwt = require('jsonwebtoken');
const app = express();

app.post('/auth/erebus', (req, res) => {
  // Validate your user here
  const token = jwt.sign(
    {
      sub: 'user-123',
      erebus_api_key: 'your-api-key-here'
    },
    'your-jwt-secret',
    { expiresIn: '1h' }
  );

  res.json({ token });
});

app.listen(3001);

Authentication Required

Erebus requires JWT tokens for authentication. The token must include your API key in the erebus_api_key field. See our authentication guide for detailed setup.