Installation

Installation Methods

Sockudo can be installed in several ways depending on your needs:

Docker

Recommended for production

From Source

For development and customization

Pre-built Binaries

Quick installation (coming soon)

Docker Installation

Docker is the recommended installation method for production deployments. It includes all dependencies and is easy to update.

Production Deployment

Clone the Repository

git clone https://github.com/sockudo/sockudo.git
cd sockudo

Configure Environment

Copy the example environment file and customize it:

cp .env.example .env

Edit .env with your production settings:

.env

# Environment
ENVIRONMENT=production
DEBUG_MODE=false

# Server
PORT=6001
HOST=0.0.0.0

# Application credentials (CHANGE THESE!)
SOCKUDO_DEFAULT_APP_ID=my-production-app
SOCKUDO_DEFAULT_APP_KEY=my-secure-key
SOCKUDO_DEFAULT_APP_SECRET=my-secure-secret-generate-with-openssl

# Scaling backend
ADAPTER_DRIVER=redis
CACHE_DRIVER=redis
QUEUE_DRIVER=redis

# Redis connection
DATABASE_REDIS_HOST=redis
DATABASE_REDIS_PORT=6379
DATABASE_REDIS_PASSWORD=your-redis-password

# SSL/TLS (recommended for production)
SSL_ENABLED=true
SSL_CERT_PATH=/app/ssl/cert.pem
SSL_KEY_PATH=/app/ssl/key.pem

# Rate limiting
RATE_LIMITER_ENABLED=true
RATE_LIMITER_DRIVER=redis

Generate secure credentials:

# Generate app secret
openssl rand -base64 32

# Generate Redis password
openssl rand -base64 32

Start the Production Stack

# Start with production config
make prod

# Or manually with docker compose
docker compose -f docker-compose.prod.yml up -d

This starts:

Sockudo server (with resource limits)
Redis (persistent storage)
Prometheus metrics
Grafana dashboard (optional)

Verify Installation

# Check health
curl http://localhost:6001/up/my-production-app

# Check metrics
curl http://localhost:9601/metrics

# View logs
docker logs sockudo-sockudo-1

Docker Compose Configurations

Sockudo includes several docker-compose configurations:

File	Use Case	Command
`docker-compose.yml`	Development with Redis	`make up`
`docker-compose.prod.yml`	Production with monitoring	`make prod`
`docker-compose.multinode.yml`	Multi-node testing	`docker compose -f docker-compose.multinode.yml up`
`docker-compose.redis-cluster.yml`	Redis Cluster backend	`docker compose -f docker-compose.redis-cluster.yml up`
`docker-compose.unix-socket.yml`	Unix socket (for Nginx proxy)	`docker compose -f docker-compose.unix-socket.yml up`

Building from Source

Building from source requires Rust 1.90 or later. This method is recommended for development or when you need custom feature flags.

Prerequisites

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Verify installation:

rustc --version  # Should be 1.90 or later
cargo --version

Install System Dependencies (Optional)

Depending on which features you enable, you may need:Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y pkg-config libssl-dev cmake

macOS:

brew install pkg-config openssl cmake

Windows:

Install Visual Studio Build Tools
Install CMake

Build with Feature Flags

Sockudo uses Cargo feature flags to compile only the backends you need, significantly reducing build times.

The default local feature includes only in-memory implementations with no external dependencies. This builds 30-50% faster than the full build.

# Fastest build - no external dependencies
# Includes: Local adapter, memory cache, memory queue
cd sockudo
cargo build --release

# Run with local backend
./target/release/sockudo

Available Features

Meta Features
Adapters
App Managers
Cloud Services

Feature	Description
`local` (default)	Local/in-memory only - no external dependencies
`full`	Enables all available backends

Feature	Description	Use Case
`redis`	Redis adapter, cache, queue, rate limiter	Single Redis instance
`redis-cluster`	Redis Cluster support (implies `redis`)	Multi-node Redis
`nats`	NATS adapter for horizontal scaling	Alternative to Redis

Feature	Description
`mysql`	MySQL app manager
`postgres`	PostgreSQL app manager
`dynamodb`	AWS DynamoDB app manager
`scylladb`	ScyllaDB app manager

Feature	Description
`sqs`	AWS SQS queue backend
`lambda`	AWS Lambda webhook support

Custom Feature Combinations

Combine features based on your needs:

# Redis + PostgreSQL + NATS
cargo build --release --features "redis,postgres,nats"

# Redis Cluster + MySQL + SQS
cargo build --release --features "redis-cluster,mysql,sqs"

# Minimal cloud setup: Redis + DynamoDB + Lambda
cargo build --release --features "redis,dynamodb,lambda"

Build Performance Comparison

Configuration	Build Time	Binary Size	Use Case
`local` (default)	~2-3 min	~15 MB	Local development
`redis`	~3-4 min	~20 MB	Single-node production
`redis-cluster,mysql`	~4-5 min	~25 MB	Multi-node production
`full`	~6-8 min	~35 MB	Maximum flexibility

For development, stick with the default local feature to keep build times fast. Switch to production features only when deploying.

Configuration

After installation, configure Sockudo using environment variables or a config file.

Environment Variables

Create a .env file in the project root:

# Server
PORT=6001
HOST=0.0.0.0

# App credentials
SOCKUDO_DEFAULT_APP_ID=my-app
SOCKUDO_DEFAULT_APP_KEY=my-key
SOCKUDO_DEFAULT_APP_SECRET=my-secret

# Local backend (no external dependencies)
ADAPTER_DRIVER=local

Config File

Alternatively, use a JSON config file (config/config.json):

config/config.json

{
  "port": 6001,
  "host": "0.0.0.0",
  
  "adapter": {
    "driver": "redis"
  },
  
  "database": {
    "redis": {
      "host": "localhost",
      "port": 6379,
      "password": "your-password",
      "db": 0,
      "key_prefix": "sockudo:"
    }
  },
  
  "websocket": {
    "max_messages": 1000,
    "max_bytes": 1048576,
    "disconnect_on_buffer_full": true,
    "auto_ping": true,
    "ping_interval": 30
  },
  
  "delta_compression": {
    "enabled": true,
    "algorithm": "fossil",
    "full_message_interval": 10
  }
}

Start with custom config:

./target/release/sockudo --config /path/to/config.json

Platform-Specific Notes

Linux

Recommended for production. Tested on Ubuntu 20.04+, Debian 11+, and RHEL 8+.

# Install dependencies
sudo apt-get update
sudo apt-get install -y pkg-config libssl-dev cmake

# Build
cargo build --release --features full

# Install binary
sudo cp target/release/sockudo /usr/local/bin/

macOS

Supports both Intel (x86_64) and Apple Silicon (ARM64).

# Install dependencies
brew install pkg-config openssl cmake

# Build
cargo build --release --features full

Windows

Windows support is available but less tested than Linux/macOS.

# Install Visual Studio Build Tools first
# Then build
cargo build --release --features full

For production on Windows, consider using Docker or WSL2 for better compatibility.

Running as a Service

systemd (Linux)

Create /etc/systemd/system/sockudo.service:

[Unit]
Description=Sockudo WebSocket Server
After=network.target redis.service

[Service]
Type=simple
User=sockudo
Group=sockudo
WorkingDirectory=/opt/sockudo
EnvironmentFile=/opt/sockudo/.env
ExecStart=/usr/local/bin/sockudo --config /opt/sockudo/config/config.json
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable sockudo
sudo systemctl start sockudo
sudo systemctl status sockudo

Docker Compose (Recommended)

Use Docker Compose with restart policies:

docker-compose.yml

services:
  sockudo:
    image: sockudo/sockudo:latest
    restart: unless-stopped
    ports:
      - "6001:6001"
      - "9601:9601"
    env_file:
      - .env
    depends_on:
      - redis

Updating Sockudo

Docker

# Pull latest image
docker compose pull

# Restart with new image
docker compose up -d

From Source

git pull origin main
cargo build --release --features full
sudo systemctl restart sockudo

Verification

After installation, verify everything works:

# Check server health
curl http://localhost:6001/up/my-app

# Check metrics
curl http://localhost:9601/metrics

# Check WebSocket connection
wscat -c ws://localhost:6001/app/my-key

Next Steps

Configuration Guide

Configure Sockudo for your environment

Scaling Guide

Scale horizontally with Redis or NATS

Security Best Practices

Secure your Sockudo deployment

Monitoring

Set up Prometheus and Grafana

Troubleshooting

Build fails with OpenSSL errors

Install OpenSSL development headers:Ubuntu/Debian:

sudo apt-get install pkg-config libssl-dev

macOS:

brew install openssl
export OPENSSL_DIR=$(brew --prefix openssl)

Feature not available

Make sure you built with the required feature flag:

# Example: Redis feature required
cargo build --release --features redis

If you try to use ADAPTER_DRIVER=redis without the redis feature, Sockudo will fall back to local with a warning.

Out of memory during build

Rust compilation can be memory-intensive. Try:

# Build with fewer parallel jobs
cargo build --release -j 2

# Or use the default feature (faster, less memory)
cargo build --release

Permission denied on Unix socket

If using Unix sockets, ensure proper permissions:

# Set socket permissions in .env
UNIX_SOCKET_PERMISSION_MODE=660

# Ensure user is in correct group
sudo usermod -a -G sockudo nginx

Getting Started

Core Concepts

Configuration

Deployment

Advanced Features

Installation Methods

Docker

From Source

Pre-built Binaries

Docker Installation

Production Deployment

Docker Compose Configurations

Building from Source

Prerequisites

Build with Feature Flags

Available Features

Custom Feature Combinations

Build Performance Comparison

Configuration

Environment Variables

Config File

Platform-Specific Notes

Linux

macOS

Windows

Running as a Service

systemd (Linux)

Docker Compose (Recommended)

Updating Sockudo

Docker

From Source

Verification

Next Steps

Configuration Guide

Scaling Guide

Security Best Practices

Monitoring

Troubleshooting

Getting Started

Core Concepts

Configuration

Deployment

Advanced Features

Documentation Index

​Installation Methods

Docker

From Source

Pre-built Binaries

​Docker Installation

​Production Deployment

​Docker Compose Configurations

​Building from Source

​Prerequisites

​Build with Feature Flags

​Available Features

​Custom Feature Combinations

​Build Performance Comparison

​Configuration

​Environment Variables

​Config File

​Platform-Specific Notes

​Linux

​macOS

​Windows

​Running as a Service

​systemd (Linux)

​Docker Compose (Recommended)

​Updating Sockudo

​Docker

​From Source

​Verification

​Next Steps

Configuration Guide

Scaling Guide

Security Best Practices

Monitoring

​Troubleshooting

Installation Methods

Docker Installation

Production Deployment

Docker Compose Configurations

Building from Source

Prerequisites

Build with Feature Flags

Available Features

Custom Feature Combinations

Build Performance Comparison

Configuration

Environment Variables

Config File

Platform-Specific Notes

Linux

macOS

Windows

Running as a Service

systemd (Linux)

Docker Compose (Recommended)

Updating Sockudo

Docker

From Source

Verification

Next Steps

Troubleshooting