Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sockudo/sockudo/llms.txt

Use this file to discover all available pages before exploring further.

​
Get Started in 5 Minutes

This quickstart guide will have you running Sockudo with Docker and connecting your first client.
This guide uses Docker for simplicity. For production deployments or building from source, see the Installation guide.
1

Prerequisites

Make sure you have the following installed:
  • Docker (v20.10 or later)
  • Docker Compose (v2.0 or later)
  • Node.js (v16 or later, for testing the client)
Verify your installation:
docker --version
docker compose version
node --version
2

Clone and Start Sockudo

Clone the repository and start Sockudo with Docker Compose:
# Clone the repository
git clone https://github.com/sockudo/sockudo.git
cd sockudo

# Start Sockudo with Redis
make up
This will start:
  • Sockudo server on http://localhost:6001
  • Redis (for scaling and state management)
  • Prometheus metrics on http://localhost:9601/metrics
The make up command uses docker-compose.yml which includes Redis. For a minimal local setup without Redis, use docker compose up sockudo instead.
Wait for the servers to start. You should see:
✓ Sockudo server started on 0.0.0.0:6001
✓ Metrics server started on 0.0.0.0:9601
3

Verify Sockudo is Running

Test the health endpoint:
curl http://localhost:6001/up/demo-app
You should see:
{"status":"ok"}
The default app credentials are:
  • App ID: demo-app
  • App Key: demo-key
  • App Secret: demo-secret
These are fine for local development but should be changed in production.
4

Connect Your First Client

Create a simple HTML client to test the connection.Create a file named test-client.html:
test-client.html
<!DOCTYPE html>
<html>
<head>
  <title>Sockudo Test Client</title>
  <script src="https://js.pusher.com/8.2.0/pusher.min.js"></script>
</head>
<body>
  <h1>Sockudo Test Client</h1>
  <div id="status">Connecting...</div>
  <div id="messages"></div>
  
  <script>
    // Initialize Pusher client (Sockudo is Pusher-compatible)
    const pusher = new Pusher('demo-key', {
      wsHost: 'localhost',
      wsPort: 6001,
      cluster: '',
      forceTLS: false,
      enabledTransports: ['ws'],
      disableStats: true
    });
    
    // Connection status
    pusher.connection.bind('connected', () => {
      document.getElementById('status').innerHTML = 
        '<span style="color: green">✓ Connected to Sockudo</span>';
      console.log('Connected to Sockudo!');
    });
    
    pusher.connection.bind('error', (err) => {
      document.getElementById('status').innerHTML = 
        '<span style="color: red">✗ Connection error</span>';
      console.error('Connection error:', err);
    });
    
    // Subscribe to a channel
    const channel = pusher.subscribe('test-channel');
    
    channel.bind('pusher:subscription_succeeded', () => {
      console.log('Subscribed to test-channel');
    });
    
    // Listen for events
    channel.bind('test-event', (data) => {
      console.log('Received event:', data);
      const messagesDiv = document.getElementById('messages');
      messagesDiv.innerHTML += `<p><strong>Event received:</strong> ${JSON.stringify(data)}</p>`;
    });
  </script>
</body>
</html>
Open the file in your browser:
open test-client.html  # macOS
xdg-open test-client.html  # Linux
start test-client.html  # Windows
You should see ”✓ Connected to Sockudo” in the page.
5

Send Your First Event

Now let’s trigger an event from the server to your connected client.Use curl to send an event via the HTTP API:
curl -X POST http://localhost:6001/apps/demo-app/events \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-event",
    "channel": "test-channel",
    "data": "{\"message\": \"Hello from Sockudo!\"}"
  }'
The data field must be a JSON-encoded string, not a direct object. This matches the Pusher protocol.
You should see the event appear in your browser:
Event received: {"message": "Hello from Sockudo!"}
Success! You’ve successfully:
  • Started Sockudo
  • Connected a WebSocket client
  • Sent and received a real-time event

​
Using pusher-js in Node.js

For server-side testing or Node.js applications: 
// Install pusher-js first: npm install pusher-js
const Pusher = require('pusher-js');

const pusher = new Pusher('demo-key', {
  wsHost: 'localhost',
  wsPort: 6001,
  forceTLS: false,
  disableStats: true
});

pusher.connection.bind('connected', () => {
  console.log('✓ Connected to Sockudo');
});

const channel = pusher.subscribe('my-channel');

channel.bind('my-event', (data) => {
  console.log('Received:', data);
});

​
Next Steps

Channel Types

Learn about public, private, and presence channels

Authentication

Set up channel authentication for private channels

Configuration

Configure Sockudo for production

Scaling

Scale horizontally with Redis or NATS

​
Troubleshooting

Check that Sockudo is running:
docker ps | grep sockudo
curl http://localhost:6001/up/demo-app
Check Docker logs:
docker logs sockudo-sockudo-1
Verify the channel name matches exactly:
  • Client subscribes to: test-channel
  • Server triggers on: test-channel
Check that the app ID in the trigger URL matches your client’s app key.
Sockudo allows all origins by default in development. If you’re seeing CORS errors, check your Docker logs:
docker logs sockudo-sockudo-1
Set CORS_ORIGINS=* in your .env file if needed.
If port 6001 is already in use, change it in .env:
PORT=6002
Then restart:
make down && make up

​
Clean Up

To stop Sockudo and remove containers: 
# Stop containers
make down

# Stop and remove volumes (clears Redis data)
make clean
Ready for production? Check out the Installation guide for building from source and advanced deployment options.