Docker Deployment

Overview

Sockudo provides production-ready Docker images with multi-stage builds for optimal performance and security. Deploy as a single container or scale horizontally with Docker Compose.

Quick Start

# Clone and start with Docker Compose
git clone https://github.com/sockudo/sockudo.git
cd sockudo
make up

# Server runs on http://localhost:6001
# Metrics on http://localhost:9601/metrics

Dockerfile Structure

Sockudo uses a multi-stage Docker build for minimal runtime images:

Build Stage

FROM rust:1.93-bookworm AS builder

# Install dependencies for all features
RUN apt-get update && apt-get install -y \
    pkg-config \
    libpq-dev \
    libmariadb-dev \
    cmake \
    libclang-dev \
    clang

# Build with full feature set
RUN cargo build --release --features full
RUN strip target/release/sockudo

Runtime Stage

FROM debian:bookworm-slim AS runtime

# Install only runtime dependencies
RUN apt-get update && apt-get install -y \
    ca-certificates \
    libpq5 \
    curl

# Non-root user for security
RUN groupadd -r sockudo && useradd -r -g sockudo sockudo

Basic Docker Compose

Minimal configuration for development:

services:
  sockudo:
    build:
      context: .
      dockerfile: Dockerfile
      target: runtime
    container_name: sockudo-server
    restart: unless-stopped
    
    environment:
      RUST_LOG: "info,sockudo=debug"
      DEBUG: "false"
      HOST: "0.0.0.0"
      PORT: "6001"
      METRICS_PORT: "9601"
      
      # Database Configuration
      DATABASE_REDIS_HOST: "redis"
      DATABASE_REDIS_PORT: "6379"
      DATABASE_REDIS_PASSWORD: "${REDIS_PASSWORD:-}"
      
      # Driver Configuration
      ADAPTER_DRIVER: "redis"
      CACHE_DRIVER: "redis"
      QUEUE_DRIVER: "redis"
      METRICS_DRIVER: "prometheus"
      
      # Default App Configuration
      SOCKUDO_DEFAULT_APP_ID: "demo-app"
      SOCKUDO_DEFAULT_APP_KEY: "demo-key"
      SOCKUDO_DEFAULT_APP_SECRET: "demo-secret"
      SOCKUDO_DEFAULT_APP_MAX_CONNECTIONS: "1000"
    
    ports:
      - "6001:6001"  # WebSocket/HTTP API
      - "9601:9601"  # Metrics
    
    volumes:
      - ./config:/app/config:ro
      - ./logs:/app/logs
    
    depends_on:
      redis:
        condition: service_healthy

  redis:
    image: redis:7-alpine
    container_name: sockudo-redis
    restart: unless-stopped
    
    command: >
      sh -c "
        if [ -n \"$${REDIS_PASSWORD}\" ]; then
          redis-server --requirepass $${REDIS_PASSWORD} --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
        else
          redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
        fi
      "
    
    volumes:
      - redis-data:/data
    
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  redis-data:
    driver: local

networks:
  sockudo-network:
    driver: bridge

Volume Mounts

Configuration Directory

Mount your config files as read-only:

volumes:
  - ./config:/app/config:ro

The config directory should contain:

config.json - Main configuration file
apps.json - Application definitions (if using file-based app manager)

Log Directory

Persist logs to host:

volumes:
  - ./logs:/app/logs

SSL Certificates

Mount certificates for production SSL:

volumes:
  - ./ssl:/app/ssl:ro
  # Or use Let's Encrypt
  - /etc/letsencrypt/live/${DOMAIN}:/app/ssl:ro

Then configure SSL in environment:

environment:
  SSL_ENABLED: "true"
  SSL_CERT_PATH: "/app/ssl/fullchain.pem"
  SSL_KEY_PATH: "/app/ssl/privkey.pem"

Environment Variables

Core Settings

environment:
  # Server Configuration
  HOST: "0.0.0.0"
  PORT: "6001"
  DEBUG: "false"
  RUST_LOG: "info,sockudo=info"
  
  # Instance Identity
  INSTANCE_PROCESS_ID: "${HOSTNAME:-sockudo-1}"
  SHUTDOWN_GRACE_PERIOD: "10"

Driver Configuration

environment:
  # Horizontal Scaling
  ADAPTER_DRIVER: "redis"  # local, redis, redis-cluster, nats
  
  # Caching
  CACHE_DRIVER: "redis"  # memory, redis, redis-cluster, none
  
  # Background Jobs
  QUEUE_DRIVER: "redis"  # memory, redis, redis-cluster, sqs, none
  
  # App Storage
  APP_MANAGER_DRIVER: "memory"  # memory, mysql, postgres, dynamodb
  
  # Rate Limiting
  RATE_LIMITER_DRIVER: "redis"  # memory, redis, redis-cluster
  
  # Metrics
  METRICS_DRIVER: "prometheus"
  METRICS_ENABLED: "true"
  METRICS_HOST: "0.0.0.0"
  METRICS_PORT: "9601"
  METRICS_PROMETHEUS_PREFIX: "sockudo_"

Redis Configuration

environment:
  # Redis Connection
  DATABASE_REDIS_HOST: "redis"
  DATABASE_REDIS_PORT: "6379"
  DATABASE_REDIS_PASSWORD: "${REDIS_PASSWORD:-}"
  DATABASE_REDIS_DB: "0"
  DATABASE_REDIS_KEY_PREFIX: "sockudo:"

Or use a single connection string:

environment:
  REDIS_URL: "redis://:password@redis:6379/0"

Default App Configuration

environment:
  SOCKUDO_DEFAULT_APP_ID: "my-app"
  SOCKUDO_DEFAULT_APP_KEY: "app-key-12345"
  SOCKUDO_DEFAULT_APP_SECRET: "app-secret-67890"
  SOCKUDO_DEFAULT_APP_ENABLED: "true"
  SOCKUDO_DEFAULT_APP_MAX_CONNECTIONS: "10000"
  SOCKUDO_DEFAULT_APP_MAX_CLIENT_EVENTS_PER_SECOND: "100"
  SOCKUDO_DEFAULT_APP_MAX_READ_REQUESTS_PER_SECOND: "100"
  SOCKUDO_ENABLE_CLIENT_MESSAGES: "true"
  SOCKUDO_DEFAULT_APP_ENABLE_USER_AUTHENTICATION: "false"
  SOCKUDO_DEFAULT_APP_ALLOWED_ORIGINS: "https://app.example.com,https://admin.example.com"

Health Checks

Sockudo Health Check

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:6001/up/demo-app"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 30s

Change /up/demo-app to match your app ID, or use /up for general health check.

Redis Health Check

healthcheck:
  test: ["CMD", "redis-cli", "ping"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 10s

With password authentication:

healthcheck:
  test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]

Resource Limits

Set CPU and memory limits for production:

deploy:
  resources:
    limits:
      memory: 512M
      cpus: '1.0'
    reservations:
      memory: 256M
      cpus: '0.5'

Adjust based on your deployment scenario (see Production page).

Logging Configuration

JSON Logs (for production)

environment:
  LOG_OUTPUT_FORMAT: "json"  # Must be environment variable
  LOG_INCLUDE_TARGET: "true"

logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

Human-Readable Logs (for development)

environment:
  LOG_OUTPUT_FORMAT: "human"
  LOG_COLORS_ENABLED: "true"
  LOG_INCLUDE_TARGET: "true"

logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

Multi-Container Setup

Include additional services:

services:
  sockudo:
    # ... sockudo config

  redis:
    # ... redis config

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: sockudo
      MYSQL_USER: sockudo
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - mysql-data:/var/lib/mysql

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus-data:/prometheus

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
    volumes:
      - grafana-data:/var/lib/grafana

volumes:
  redis-data:
  mysql-data:
  prometheus-data:
  grafana-data:

Building Custom Images

Build with Specific Features

# Build stage with Redis only
RUN cargo build --release --features "redis"

# Build with Redis Cluster and PostgreSQL
RUN cargo build --release --features "redis-cluster,postgres"

# Full production build
RUN cargo build --release --features full

Custom Entrypoint

# Copy custom entrypoint script
COPY docker-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/docker-entrypoint.sh

ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["sockudo", "--config", "/app/config/config.json"]

Docker Commands

# Start services
docker-compose up -d

# View logs
docker-compose logs -f sockudo

# Check health
docker-compose ps

# Scale instances (requires load balancer)
docker-compose up -d --scale sockudo=3

# Stop services
docker-compose down

# Remove volumes (careful!)
docker-compose down -v

# Rebuild after code changes
docker-compose up -d --build

Getting Started

Core Concepts

Configuration

Deployment

Advanced Features

Docker Deployment

Overview

Quick Start

Dockerfile Structure

Build Stage

Runtime Stage

Basic Docker Compose

Volume Mounts

Configuration Directory

Log Directory

SSL Certificates

Environment Variables

Core Settings

Driver Configuration

Redis Configuration

Default App Configuration

Health Checks

Sockudo Health Check

Redis Health Check

Resource Limits

Logging Configuration

JSON Logs (for production)

Human-Readable Logs (for development)

Multi-Container Setup

Building Custom Images

Build with Specific Features

Custom Entrypoint

Docker Commands

Next Steps

Getting Started

Core Concepts

Configuration

Deployment

Advanced Features

Documentation Index

​Overview

​Quick Start

​Dockerfile Structure

​Build Stage

​Runtime Stage

​Basic Docker Compose

​Volume Mounts

​Configuration Directory

​Log Directory

​SSL Certificates

​Environment Variables

​Core Settings

​Driver Configuration

​Redis Configuration

​Default App Configuration

​Health Checks

​Sockudo Health Check

​Redis Health Check

​Resource Limits

​Logging Configuration

​JSON Logs (for production)

​Human-Readable Logs (for development)

​Multi-Container Setup

​Building Custom Images

​Build with Specific Features

​Custom Entrypoint

​Docker Commands

​Next Steps

Overview

Quick Start

Dockerfile Structure

Build Stage

Runtime Stage

Basic Docker Compose

Volume Mounts

Configuration Directory

Log Directory

SSL Certificates

Environment Variables

Core Settings

Driver Configuration

Redis Configuration

Default App Configuration

Health Checks

Sockudo Health Check

Redis Health Check

Resource Limits

Logging Configuration

JSON Logs (for production)

Human-Readable Logs (for development)

Multi-Container Setup

Building Custom Images

Build with Specific Features

Custom Entrypoint

Docker Commands

Next Steps