Common Configurations
Find settings by startup, client access, Manager, and logging; expand complete defaults when needed.
Choose a task first. WK_ environment values override TOML; expand the complete field, environment, and defaults reference below.
Every deployment is a cluster
A one-node deployment is a single-node cluster. Every scenario requires node.id, node.data_dir, and cluster.listen_addr; configuration changes usually require a node restart.
Start a node
Identity, storage, and peers.
Connect clients
Gateway, API, and tokens.
Open Manager
Listener, JWT, and access.
Inspect logs
Levels and cleanup after diagnosis.
Frequently used settings
Start a node
| Use | Setting and result |
|---|---|
| Identity | node.id: Non-zero and unique; never change after data exists |
| Storage | node.data_dir: Exclusive, writable storage on a persistent, backed-up disk |
| Peers | cluster.listen_addr: Local listener; peers need real reachable addresses, never wildcards |
Choose static cluster.nodes or non-empty cluster.seeds. JSON environment lists replace the whole list.
Connect clients
| Use | Setting and result |
|---|---|
| Clients | gateway.listeners: Omission listens on all interfaces: TCP 5100 / WSMux 5200; an explicit empty list disables Gateway |
| API | api.listen_addr: Omitted or empty disables WuKongIM HTTP API; configure Gateway and Manager separately |
Keep gateway.token_auth_on=true. CONNECT exactly matches the stored device token for the same UID + device_flag; empty, missing, or mismatched tokens return ReasonAuthFail. WuKongIM HTTP API still needs a trusted network or external auth.
Open Manager
| Use | Setting and result |
|---|---|
| Listener | manager.listen_addr: omitted or empty disables Manager; use loopback / private networks with SSH or HTTPS |
| JWT | manager.auth_on: omission defaults to false; set true in production with manager.jwt_secret and manager.users |
Verify: replace example credentials, sign in, and grant only required resources and actions.
Inspect logs
log.level defaults to info; choices are debug, info, warn, and error. Use debug temporarily for diagnosis, then restore the previous level.
Complete common fields, defaults, and environment mappings
This page keeps only the settings most often consulted for startup, client access, and daily operations. Each setting can be provided through TOML or an environment variable; when both are present, the environment variable overrides the file value. See the Configuration Reference for every field and its exact semantics.
| Setting (TOML / environment) | Purpose | Defaults and cautions |
|---|---|---|
node.idWK_NODE_ID | Identifies this node as the stable identity used by messages and cluster state. | Required at startup, non-zero, and unique within the cluster; do not change it after data exists. |
node.data_dirWK_NODE_DATA_DIR | Stores this node's durable Controller, Slot, Channel, and related data. | Required at startup; the directory must be writable and should reside on persistent, backed-up storage. |
cluster.listen_addrWK_CLUSTER_LISTEN_ADDR | Listens for Cluster RPC between nodes. | Required at startup; it may bind 0.0.0.0, but the address given to peers must be reachable and must not be a wildcard. |
cluster.nodesWK_CLUSTER_NODES | Defines the static Controller voter list, with each entry containing a node id and cluster addr. | When cluster.seeds is also unset, omission or an empty list falls back to an implicit single-node cluster; it cannot be combined with non-empty cluster.seeds. The environment value must be JSON and replaces the whole list. |
cluster.slot_replica_nWK_CLUSTER_SLOT_REPLICA_N | Sets the voter replicas for each Slot Raft Group when the cluster is first initialized. | 0 derives the static voter count, or uses 1 during seed joining; existing clusters follow persisted Controller state. |
gateway.listenersWK_GATEWAY_LISTENERS | Defines the TCP or WebSocket listeners used by clients. | Omission opens WKProto TCP on 0.0.0.0:5100 and WSMux on 0.0.0.0:5200; an explicit empty list disables Gateway. The environment value must be JSON. |
gateway.token_auth_onWK_GATEWAY_TOKEN_AUTH_ON | Requires a CONNECT token to exactly match the stored device token for the same UID and device_flag. | Defaults to true; an empty token, missing record, or mismatch returns ReasonAuthFail. Disable only temporarily during a controlled compatibility migration. |
api.listen_addrWK_API_LISTEN_ADDR | Listens for the WuKongIM HTTP API, including health and switch-controlled metrics, debug, and related HTTP routes. | Omission or an empty value disables this HTTP service; it does not create client Gateway or Manager listeners. |
manager.listen_addrWK_MANAGER_LISTEN_ADDR | Listens for the separate Manager administration service. | Omission or an empty value disables Manager; bind loopback or a management address, use SSH tunneling or a private HTTPS proxy, and enable authentication. |
manager.auth_onWK_MANAGER_AUTH_ON | Requires JWT login authentication for Manager routes. | Omission is false; when true, both manager.jwt_secret and manager.users are required. |
log.levelWK_LOG_LEVEL | Sets the minimum application log level that is recorded. | Defaults to info; allowed values are debug, info, warn, and error. Avoid leaving debug enabled after production troubleshooting. |
Continue reading
- See the Configuration overview for file lookup, environment overrides, and list replacement.
- See the Configuration Reference for seed joining, channel replicas, metrics, webhooks, and every other setting.