Per-instance configuration.
Resolves explicit options first (passed to Socketelx.start_link/1),
falling back to environment variables for anything omitted — the same
variables the standalone release reads. This is what lets the exact
same code run either as a hex dependency embedded in your own
supervision tree (config passed explicitly) or as a standalone release
configured purely by env vars, with zero code differences.
Options / environment variables
| Option | Env var | Default |
|---|---|---|
:app_key | SOCKETELX_APP_KEY | "app-key" |
:app_secret | SOCKETELX_APP_SECRET | "app-secret" (public; a warning is logged, always set your own) |
:app_id | SOCKETELX_APP_ID | "app-id" |
:port | PORT | 6001 |
:webhook_url | SOCKETELX_WEBHOOK_URL | none |
:client_messages_enabled | SOCKETELX_ENABLE_CLIENT_MESSAGES | true |
:redis_url | SOCKETELX_REDIS_URL | none (single node) |
:redis_opts | — | [] (extra Redix options, e.g. ssl: true) |
:cluster | SOCKETELX_CLUSTER | none (set to erlang for the experimental Redis-free cluster mode) |
:cluster_nodes | SOCKETELX_CLUSTER_NODES | none (comma-separated Erlang node names to connect to, e.g. socketelx@host1,socketelx@host2) |
:cluster_dns | SOCKETELX_CLUSTER_DNS | none (a hostname resolving to every peer; nodes are named <basename>@<ip>) |
:cluster_node_basename | SOCKETELX_CLUSTER_NODE_BASENAME | "socketelx" (the part before @ when using :cluster_dns) |
:webhook_retries | SOCKETELX_WEBHOOK_RETRIES | 3 (retries after the first attempt; 0 disables) |
:webhook_retry_base_ms | — | 1000 (delay doubles on each retry) |
:rest_rate_limit | SOCKETELX_REST_RATE_LIMIT | none (max REST API requests per second, per instance) |
:client_event_rate_limit | SOCKETELX_CLIENT_EVENT_RATE_LIMIT | none (max client events per second, per connection) |
:max_connections | SOCKETELX_MAX_CONNECTIONS | none (max WebSocket connections on this node) |
:batch_limit | SOCKETELX_BATCH_LIMIT | 10 (max events per batch_events request) |
:metrics | SOCKETELX_METRICS | false (serve Prometheus metrics at GET /metrics) |
:metrics_token | SOCKETELX_METRICS_TOKEN | none (if set, /metrics requires Authorization: Bearer <token>) |
:allowed_origins | SOCKETELX_ALLOWED_ORIGINS | none (every origin may connect; see below) |
:max_connections_per_ip | SOCKETELX_MAX_CONNECTIONS_PER_IP | none (max simultaneous WebSocket connections from one client IP) |
:client_ip_header | SOCKETELX_CLIENT_IP_HEADER | none (read the client IP from this header, e.g. cf-connecting-ip; see below) |
:webhook_queue_path | SOCKETELX_WEBHOOK_QUEUE_PATH | none (a directory; failed webhooks are kept there and survive a restart) |
:tls_certfile | SOCKETELX_TLS_CERTFILE | none (with :tls_keyfile, serve HTTPS/WSS directly) |
:tls_keyfile | SOCKETELX_TLS_KEYFILE | none |
:apps | SOCKETELX_APPS | none (several apps in one server, see Socketelx and the multi-app guide) |
Allowed origins
Browsers send an Origin header on every WebSocket connection. With
:allowed_origins unset (or containing "*") every origin is accepted.
Otherwise the origin must match one entry: a full origin
("https://chat.example.com", scheme and port included), a bare host
("chat.example.com", any scheme or port) or a wildcard host
("*.example.com", any subdomain but not example.com itself). Give a
list, or a comma-separated string in the environment variable. A refused
connection receives pusher:error 4009 and is closed. Connections without
an Origin header (servers, mobile apps) are not affected: the check
protects against other websites using your visitors' browsers, it is not
authentication.
Setting :redis_url switches the instance to the Redis backend so
several nodes can share channels, presence and broadcasts. Setting
cluster: :erlang does the same over Erlang's own clustering with no Redis
(experimental, see Socketelx.Backend.Distributed). Without either, the
instance runs fully in-memory and needs nothing but this library. Setting
both is an error.
Summary
Functions
Whether a browser Origin header value may open a WebSocket on this
instance. nil (no header) is always allowed; see the module docs.
Types
@type t() :: %Socketelx.Config{ allowed_origins: term(), app_id: term(), app_key: term(), app_secret: term(), backend: term(), batch_limit: term(), client_event_rate_limit: term(), client_ip_header: term(), client_messages_enabled: term(), cluster: term(), cluster_dns: term(), cluster_node_basename: term(), cluster_nodes: term(), max_connections: term(), max_connections_per_ip: term(), metrics: term(), metrics_token: term(), node_id: term(), port: term(), prefix: term(), redis_opts: term(), redis_url: term(), rest_rate_limit: term(), tls_certfile: term(), tls_keyfile: term(), webhook_queue_path: term(), webhook_retries: term(), webhook_retry_base_ms: term(), webhook_url: term() }