Configuration Overview

Understanding Sockudo’s configuration hierarchy and options

Sockudo provides a flexible configuration system that allows you to configure the server through multiple methods, each with different priority levels.

Configuration Hierarchy

Configuration values are resolved in the following order (highest priority wins):

1. Environment Variables (highest priority)
2. Command-line Arguments
3. Config File (config/config.json)
4. Default Values (hardcoded, lowest priority)

This hierarchy allows you to set baseline configuration in your config file, override specific values via command-line arguments for testing, and use environment variables for production deployments.

Configuration File

The primary configuration file is config/config.json, which contains all server settings in JSON format.

Basic Structure

{
  "debug": false,
  "host": "0.0.0.0",
  "port": 6001,
  "mode": "production",
  "path_prefix": "/",
  "shutdown_grace_period": 2,
  "adapter": { ... },
  "app_manager": { ... },
  "cache": { ... },
  "queue": { ... },
  "ssl": { ... },
  "websocket": { ... }
}

Core Settings

debug · boolean · default: "false"

Enable debug logging for detailed troubleshooting. Can also be set via DEBUG or DEBUG_MODE environment variables.

host · string · default: "0.0.0.0"

Server host binding address. Use 0.0.0.0 to listen on all interfaces, or 127.0.0.1 for localhost only.

port · number · default: "6001"

WebSocket server port. Override via PORT environment variable.

mode · string · default: "production"

Server mode: production or development. Affects logging verbosity and error handling. Set via ENVIRONMENT environment variable.

path_prefix · string · default: "/"

URL path prefix for all endpoints. Useful when running behind a reverse proxy with path-based routing.

shutdown_grace_period · number · default: "2"

Graceful shutdown timeout in seconds. Allows active connections to complete before forcing shutdown.

user_authentication_timeout · number · default: "3600"

User authentication token TTL in seconds (default: 1 hour).

activity_timeout · number · default: "120"

Connection activity timeout in seconds before marking as inactive.

websocket_max_payload_kb · number · default: "64"

Maximum WebSocket message payload size in kilobytes.

Environment Variables

All configuration options can be set via environment variables. See the Environment Variables page for a complete reference.

Common Environment Variables

# Server settings
HOST=0.0.0.0
PORT=6001
ENVIRONMENT=production
DEBUG=false

# Driver selection
ADAPTER_DRIVER=redis
CACHE_DRIVER=redis
QUEUE_DRIVER=redis
APP_MANAGER_DRIVER=mysql

# Redis connection
DATABASE_REDIS_HOST=localhost
DATABASE_REDIS_PORT=6379
DATABASE_REDIS_PASSWORD=secret

Command-line Arguments

You can override configuration values using command-line flags:

# Specify config file
./sockudo --config /path/to/config.json

# Override specific settings
./sockudo --port 6002 --host 127.0.0.1

# Enable debug mode
./sockudo --debug

Configuration Sections

Sockudo’s configuration is organized into functional sections:

• Adapters - Connection management and horizontal scaling (Local, Redis, Redis Cluster, NATS)
• Backends - App managers, cache, and queue drivers
• SSL/TLS - Certificate configuration and HTTPS setup
• WebSocket - Buffer limits, compression, and connection settings
• Environment Variables - Complete reference of all environment variables

Best Practices

Development

• Use config.json for local development settings
• Set debug: true or DEBUG=true for detailed logging
• Use local adapter for single-instance testing
• Use memory drivers for app manager, cache, and queue

Production

• Use environment variables for sensitive values (passwords, secrets)
• Enable SSL/TLS with valid certificates
• Configure Redis/Redis Cluster/NATS adapter for horizontal scaling
• Use persistent storage for app manager (MySQL, PostgreSQL, DynamoDB)
• Set appropriate connection and rate limits
• Configure structured logging (LOG_OUTPUT_FORMAT=json)
• Enable metrics for monitoring (METRICS_ENABLED=true)

Docker/Kubernetes

• Mount config.json as a ConfigMap
• Store secrets in environment variables or Secret objects
• Use readiness/liveness probes with /up/{app_id} endpoint
• Configure resource limits based on expected load
• Use Redis Cluster for high availability

Validation

Sockudo validates configuration at startup and will fail with descriptive error messages if:

• Required fields are missing
• Values are out of valid range
• Backend drivers are configured but the feature is not compiled in
• SSL certificates are enabled but files don’t exist
• Redis/database connections cannot be established

Always check server logs during startup to ensure configuration is valid.

Next Steps

Adapter Configuration

Configure horizontal scaling with Redis, Redis Cluster, or NATS

Backend Drivers

Set up app managers, cache, and queue backends

SSL/TLS Setup

Enable HTTPS with certificates

WebSocket Settings

Configure buffers and connection limits