Environment Variables Reference

Complete list of all Sockudo environment variables with defaults

This page documents all environment variables supported by Sockudo. Environment variables have the highest priority in the configuration hierarchy.

Server Settings

ENVIRONMENT · string · default: "development"

Server mode: development, staging, or production. Affects logging verbosity.

DEBUG · boolean · default: "false"

Enable debug logging. Takes precedence over DEBUG_MODE.

DEBUG_MODE · boolean · default: "false"

Enable debug logging (alternative to DEBUG).

LOG_LEVEL · string · default: "info"

Log level: error, warn, info, debug, or trace.

HOST · string · default: "0.0.0.0"

Server host binding address.

PORT · number · default: "6001"

WebSocket server port.

METRICS_PORT · number · default: "9601"

Prometheus metrics endpoint port.

Logging Configuration

LOG_OUTPUT_FORMAT · string · default: "human"

Log format: human or json. Must be set at startup via environment variable (cannot be set in config file).

LOG_COLORS_ENABLED · boolean · default: "true"

Enable/disable colors in human format logs.

LOG_INCLUDE_TARGET · boolean · default: "true"

Include module target in log output.

LOG_FORMAT · string · default: "text"

Structured logging format: text or json.

LOG_FILE_PATH · string

Path to log file (if logging to file).

LOG_MAX_SIZE · string · default: "10m"

Maximum log file size before rotation.

LOG_MAX_FILES · number · default: "3"

Number of rotated log files to keep.

Driver Configuration

ADAPTER_DRIVER · string · default: "local"

Adapter driver: local, redis, redis-cluster, or nats.

ADAPTER_ENABLE_SOCKET_COUNTING · boolean · default: "true"

Enable socket counting for get_sockets_count API.

CACHE_DRIVER · string · default: "memory"

Cache driver: memory, redis, redis-cluster, or none.

QUEUE_DRIVER · string · default: "memory"

Queue driver: memory, redis, redis-cluster, sqs, or none.

APP_MANAGER_DRIVER · string · default: "memory"

App manager driver: memory, mysql, postgresql, dynamodb, or scylla.

METRICS_DRIVER · string · default: "prometheus"

Metrics driver: prometheus.

RATE_LIMITER_DRIVER · string · default: "memory"

Rate limiter driver: memory, redis, or redis-cluster.

Redis Configuration

REDIS_URL · string

Complete Redis connection URL. Overrides all individual Redis settings. Format: redis://[username:password@]host:port/db.

DATABASE_REDIS_HOST · string · default: "localhost"

Redis server hostname.

DATABASE_REDIS_PORT · number · default: "6379"

Redis server port.

DATABASE_REDIS_USERNAME · string

Redis username (for Redis 6+ ACL).

DATABASE_REDIS_PASSWORD · string

Redis password.

DATABASE_REDIS_DB · number · default: "0"

Redis database number (0-15).

DATABASE_REDIS_KEY_PREFIX · string · default: "sockudo:"

Prefix for all Redis keys.

REDIS_PASSWORD · string

Redis password (alternative to DATABASE_REDIS_PASSWORD).

REDIS_CONNECTION_POOL_SIZE · number · default: "10"

Redis connection pool size.

Redis Cluster Configuration

REDIS_CLUSTER_NODES · string

Comma-separated list of Redis Cluster nodes. Format: host1:port1,host2:port2 or redis://host:port.

DATABASE_REDIS_CLUSTER_NODES · string

Alternative to REDIS_CLUSTER_NODES.

DATABASE_REDIS_CLUSTER_USERNAME · string

Redis Cluster username.

DATABASE_REDIS_CLUSTER_PASSWORD · string

Redis Cluster password.

DATABASE_REDIS_CLUSTER_USE_TLS · boolean · default: "false"

Use TLS for Redis Cluster connections.

REDIS_CLUSTER_QUEUE_CONCURRENCY · number · default: "5"

Queue concurrency for Redis Cluster.

REDIS_CLUSTER_QUEUE_PREFIX · string · default: "sockudo_queue:"

Key prefix for Redis Cluster queue.

MySQL Configuration

DATABASE_MYSQL_HOST · string · default: "mysql"

MySQL server hostname.

DATABASE_MYSQL_PORT · number · default: "3306"

MySQL server port.

DATABASE_MYSQL_USERNAME · string · default: "sockudo"

MySQL username.

DATABASE_MYSQL_PASSWORD · string

MySQL password.

DATABASE_MYSQL_DATABASE · string · default: "sockudo"

MySQL database name.

DATABASE_MYSQL_TABLE_NAME · string · default: "applications"

MySQL table name for applications.

DATABASE_MYSQL_POOL_MIN · number · default: "2"

Minimum MySQL connection pool size.

DATABASE_MYSQL_POOL_MAX · number · default: "10"

Maximum MySQL connection pool size.

MYSQL_ROOT_PASSWORD · string

MySQL root password (for Docker deployments).

MYSQL_PASSWORD · string

MySQL password (alternative).

PostgreSQL Configuration

DATABASE_POSTGRES_HOST · string · default: "postgres"

PostgreSQL server hostname.

DATABASE_POSTGRES_PORT · number · default: "5432"

PostgreSQL server port.

DATABASE_POSTGRES_USERNAME · string · default: "sockudo"

PostgreSQL username.

DATABASE_POSTGRES_PASSWORD · string

PostgreSQL password.

DATABASE_POSTGRES_DATABASE · string · default: "sockudo"

PostgreSQL database name.

DATABASE_POSTGRES_POOL_MIN · number · default: "2"

Minimum PostgreSQL connection pool size.

DATABASE_POSTGRES_POOL_MAX · number · default: "10"

Maximum PostgreSQL connection pool size.

DynamoDB Configuration

DATABASE_DYNAMODB_REGION · string · default: "us-east-1"

AWS region for DynamoDB.

DATABASE_DYNAMODB_TABLE_NAME · string · default: "sockudo-applications"

DynamoDB table name.

DATABASE_DYNAMODB_ENDPOINT_URL · string

Custom DynamoDB endpoint (for LocalStack or VPC endpoints).

NATS Configuration

NATS_SERVERS · string

Comma-separated list of NATS servers. Format: nats://host:port.

NATS_USERNAME · string

NATS username.

NATS_PASSWORD · string

NATS password.

NATS_TOKEN · string

NATS authentication token.

NATS_CONNECTION_TIMEOUT_MS · number · default: "5000"

NATS connection timeout in milliseconds.

NATS_REQUEST_TIMEOUT_MS · number · default: "5000"

NATS request timeout in milliseconds.

AWS Configuration

AWS_REGION · string · default: "us-east-1"

AWS region.

AWS_ACCESS_KEY_ID · string

AWS access key ID.

AWS_SECRET_ACCESS_KEY · string

AWS secret access key.

AWS_PROFILE · string · default: "default"

AWS CLI profile name.

SQS Queue Configuration

QUEUE_SQS_REGION · string · default: "us-east-1"

AWS region for SQS.

QUEUE_SQS_VISIBILITY_TIMEOUT · number · default: "30"

SQS message visibility timeout in seconds.

QUEUE_SQS_MAX_MESSAGES · number · default: "10"

Maximum messages to receive per batch.

QUEUE_SQS_WAIT_TIME_SECONDS · number · default: "5"

Long polling wait time in seconds.

QUEUE_SQS_CONCURRENCY · number · default: "5"

Number of concurrent SQS workers.

QUEUE_SQS_FIFO · boolean · default: "false"

Use FIFO queue.

QUEUE_SQS_ENDPOINT_URL · string

Custom SQS endpoint (for LocalStack).

SSL/TLS Configuration

SSL_ENABLED · boolean · default: "false"

Enable SSL/TLS.

SSL_CERT_PATH · string · default: "/app/ssl/cert.pem"

Path to SSL certificate file.

SSL_KEY_PATH · string · default: "/app/ssl/key.pem"

Path to SSL private key file.

SSL_REDIRECT_HTTP · boolean · default: "false"

Redirect HTTP to HTTPS.

SSL_HTTP_PORT · number · default: "80"

HTTP port for redirects.

DOMAIN · string · default: "localhost"

Domain name for SSL certificates.

Unix Socket Configuration

UNIX_SOCKET_ENABLED · boolean · default: "false"

Enable Unix socket server.

UNIX_SOCKET_PATH · string · default: "/var/run/sockudo/sockudo.sock"

Unix socket file path.

UNIX_SOCKET_PERMISSION_MODE · string · default: "660"

Socket file permissions in octal (e.g., “660”, “755”).

WebSocket Configuration

WEBSOCKET_MAX_PAYLOAD_KB · number · default: "64"

Maximum message payload size in kilobytes.

WEBSOCKET_MAX_MESSAGES · number · default: "1000"

Maximum messages buffered per connection. Set to “none” or “0” to disable.

WEBSOCKET_MAX_BYTES · number · default: "1048576"

Maximum bytes buffered per connection. Set to “none” or “0” to disable.

WEBSOCKET_DISCONNECT_ON_BUFFER_FULL · boolean · default: "false"

Disconnect clients when buffer is full (vs. dropping messages).

WEBSOCKET_MAX_MESSAGE_SIZE · number · default: "67108864"

Maximum WebSocket message size in bytes (64MB).

WEBSOCKET_MAX_FRAME_SIZE · number · default: "16777216"

Maximum WebSocket frame size in bytes (16MB).

WEBSOCKET_WRITE_BUFFER_SIZE · number · default: "16384"

Write buffer size in bytes (16KB).

WEBSOCKET_MAX_BACKPRESSURE · number · default: "1048576"

Maximum backpressure in bytes (1MB).

WEBSOCKET_AUTO_PING · boolean · default: "true"

Enable automatic WebSocket ping frames.

WEBSOCKET_PING_INTERVAL · number · default: "30"

Ping interval in seconds.

WEBSOCKET_IDLE_TIMEOUT · number · default: "120"

Idle timeout in seconds.

WEBSOCKET_COMPRESSION · string · default: "disabled"

WebSocket compression: enabled or disabled.

Application Configuration

SOCKUDO_DEFAULT_APP_ID · string · default: "demo-app"

Default application ID.

SOCKUDO_DEFAULT_APP_KEY · string · default: "demo-key"

Default application key.

SOCKUDO_DEFAULT_APP_SECRET · string · default: "demo-secret"

Default application secret.

SOCKUDO_DEFAULT_APP_ENABLED · boolean · default: "true"

Enable default application.

SOCKUDO_ENABLE_CLIENT_MESSAGES · boolean · default: "true"

Enable client-to-client messages.

SOCKUDO_DEFAULT_APP_ENABLE_USER_AUTHENTICATION · boolean · default: "false"

Enable user authentication for default app.

SOCKUDO_DEFAULT_APP_ENABLE_WATCHLIST_EVENTS · boolean · default: "false"

Enable watchlist events for default app.

SOCKUDO_DEFAULT_APP_ALLOWED_ORIGINS · string

Comma-separated list of allowed origins. Supports wildcards (e.g., https://app.example.com,*.staging.example.com).

SOCKUDO_DEFAULT_APP_MAX_CONNECTIONS · number · default: "1000"

Maximum concurrent connections per app.

SOCKUDO_DEFAULT_APP_MAX_CLIENT_EVENTS_PER_SECOND · number · default: "100"

Maximum client events per second.

SOCKUDO_DEFAULT_APP_MAX_READ_REQUESTS_PER_SECOND · number · default: "100"

Maximum read requests per second.

SOCKUDO_DEFAULT_APP_MAX_BACKEND_EVENTS_PER_SECOND · number · default: "100"

Maximum backend events per second.

SOCKUDO_DEFAULT_APP_MAX_PRESENCE_MEMBERS_PER_CHANNEL · number · default: "100"

Maximum presence members per channel.

SOCKUDO_DEFAULT_APP_MAX_PRESENCE_MEMBER_SIZE_IN_KB · number · default: "2"

Maximum presence member data size in KB.

SOCKUDO_DEFAULT_APP_MAX_CHANNEL_NAME_LENGTH · number · default: "200"

Maximum channel name length.

SOCKUDO_DEFAULT_APP_MAX_EVENT_CHANNELS_AT_ONCE · number · default: "100"

Maximum channels per event.

SOCKUDO_DEFAULT_APP_MAX_EVENT_NAME_LENGTH · number · default: "200"

Maximum event name length.

SOCKUDO_DEFAULT_APP_MAX_EVENT_PAYLOAD_IN_KB · number · default: "100"

Maximum event payload size in KB.

SOCKUDO_DEFAULT_APP_MAX_EVENT_BATCH_SIZE · number · default: "10"

Maximum events per batch.

Timeouts

SHUTDOWN_GRACE_PERIOD · number · default: "10"

Graceful shutdown timeout in seconds.

USER_AUTHENTICATION_TIMEOUT · number · default: "3600"

User authentication token TTL in seconds.

ACTIVITY_TIMEOUT · number · default: "120"

Connection activity timeout in seconds.

Rate Limiting

RATE_LIMITER_ENABLED · boolean · default: "true"

Enable rate limiting.

RATE_LIMITER_API_MAX_REQUESTS · number · default: "100"

Maximum API requests per window.

RATE_LIMITER_API_WINDOW_SECONDS · number · default: "60"

API rate limit window in seconds.

RATE_LIMITER_API_TRUST_HOPS · number · default: "0"

Number of proxy hops to trust for IP detection.

RATE_LIMITER_WS_MAX_REQUESTS · number · default: "20"

Maximum WebSocket requests per window.

RATE_LIMITER_WS_WINDOW_SECONDS · number · default: "60"

WebSocket rate limit window in seconds.

Metrics

METRICS_ENABLED · boolean · default: "true"

Enable Prometheus metrics.

METRICS_HOST · string · default: "0.0.0.0"

Metrics endpoint host.

METRICS_PROMETHEUS_PREFIX · string · default: "sockudo_"

Prometheus metrics prefix.

MONITORING_ENABLED · boolean · default: "false"

Enable monitoring stack (Prometheus + Grafana).

PROMETHEUS_RETENTION · string · default: "30d"

Prometheus data retention period.

GRAFANA_PASSWORD · string · default: "admin123"

Grafana admin password.

Queue Configuration

QUEUE_REDIS_CONCURRENCY · number · default: "5"

Redis queue worker concurrency.

QUEUE_REDIS_PREFIX · string · default: "sockudo_queue:"

Redis queue key prefix.

Webhook Configuration

WEBHOOK_BATCHING_ENABLED · boolean · default: "true"

Enable webhook batching.

WEBHOOK_BATCHING_DURATION · number · default: "50"

Webhook batching duration in milliseconds.

Cache Configuration

CACHE_TTL_SECONDS · number · default: "300"

Default cache TTL in seconds.

CACHE_CLEANUP_INTERVAL · number · default: "60"

Cache cleanup interval in seconds.

CACHE_MAX_CAPACITY · number · default: "10000"

Maximum cache capacity (items).

Database Connection Pooling

DATABASE_CONNECTION_POOL_SIZE · number · default: "10"

Database connection pool size.

DATABASE_POOLING_ENABLED · boolean · default: "true"

Enable connection pooling.

DATABASE_POOL_MIN · number · default: "2"

Minimum pool connections.

DATABASE_POOL_MAX · number · default: "10"

Maximum pool connections.

CORS Configuration

CORS_ORIGINS · string · default: "*"

Allowed CORS origins (comma-separated).

CORS_METHODS · string · default: "GET,POST,OPTIONS"

Allowed CORS methods.

CORS_HEADERS · string

Allowed CORS headers.

CORS_CREDENTIALS · boolean · default: "true"

Allow CORS credentials.

Instance Configuration

INSTANCE_PROCESS_ID · string · default: "sockudo-docker-1"

Unique process identifier for multi-instance deployments.

Cluster Configuration

CLUSTER_HOSTNAME · string · default: "localhost"

Cluster hostname.

CLUSTER_PORT · number · default: "6002"

Cluster communication port.

CLUSTER_HELLO_INTERVAL · number · default: "5000"

Cluster hello interval in milliseconds.

CLUSTER_CHECK_INTERVAL · number · default: "10000"

Cluster health check interval in milliseconds.

CLUSTER_NODE_TIMEOUT · number · default: "30000"

Cluster node timeout in milliseconds.

CLUSTER_MASTER_TIMEOUT · number · default: "60000"

Cluster master timeout in milliseconds.

Health Check

HEALTH_CHECK_INTERVAL · number · default: "30"

Health check interval in seconds.

HEALTH_CHECK_TIMEOUT · number · default: "10"

Health check timeout in seconds.

HEALTH_CHECK_RETRIES · number · default: "3"

Health check retry count.

HEALTH_CHECK_START_PERIOD · number · default: "30"

Health check start period in seconds.

Docker/Testing

SOCKUDO_REPLICAS · number · default: "1"

Number of Sockudo replicas (Docker Compose).

LOAD_BALANCER_ENABLED · boolean · default: "false"

Enable load balancer (Docker Compose).

DEV_TOOLS_ENABLED · boolean · default: "true"

Enable development tools (Redis Commander, PHPMyAdmin).

TEST_MODE · boolean · default: "false"

Enable test mode.

TEST_DATABASE_URL · string

Test database connection URL.

TEST_REDIS_URL · string

Test Redis connection URL.

JWT Configuration

JWT_SECRET · string

JWT secret for authentication. Generate with: openssl rand -base64 32.

Backup Configuration

BACKUP_RETENTION_DAYS · number · default: "30"

Backup retention period in days.

BACKUP_SCHEDULE · string · default: "0 2 * * *"

Backup schedule in cron format.

Resource Limits (Docker)

SOCKUDO_MEMORY_LIMIT · string · default: "512M"

Memory limit for Sockudo container.

SOCKUDO_CPU_LIMIT · string · default: "1.0"

CPU limit for Sockudo container.

SOCKUDO_MEMORY_RESERVATION · string · default: "256M"

Memory reservation for Sockudo container.

SOCKUDO_CPU_RESERVATION · string · default: "0.5"

CPU reservation for Sockudo container.

REDIS_MEMORY_LIMIT · string · default: "256M"

Memory limit for Redis container.

REDIS_CPU_LIMIT · string · default: "0.5"

CPU limit for Redis container.

MYSQL_MEMORY_LIMIT · string · default: "512M"

Memory limit for MySQL container.

MYSQL_CPU_LIMIT · string · default: "1.0"

CPU limit for MySQL container.

Development Ports

REDIS_COMMANDER_PORT · number · default: "8081"

Redis Commander web interface port.

PHPMYADMIN_PORT · number · default: "8080"

PHPMyAdmin web interface port.

MAILHOG_SMTP_PORT · number · default: "1025"

MailHog SMTP port.

MAILHOG_WEB_PORT · number · default: "8025"

MailHog web interface port.

Next Steps

Configuration Overview

Understand configuration hierarchy

Production Deployment

Deploy Sockudo in production