Important configuration settings

As I wrote in previous chapter configuration file must have one required option: secret.

The configuration file looks like this:

{
    "secret": "very-long-secret-key"
}

The only two who should know this secret key is Centrifugo itself and your web application backend. It is used to generate client connection tokens (more about them later), sign API requests and sign private channel subscription requests.

The next available option is connection_lifetime:

connection_lifetime – this is a time in seconds for client connection to expire. By default it equals 0 - this means that connection can live forever and will not expire. See more about connection expiration mechanism in special chapter. In most situations you don't have to explicitly set it as no connection expiration is ok for most applications.

{
    "secret": "very-long-secret-key",
    "connection_lifetime": 0
}

Let's look on options related to channels. Channel is an entity to which clients can subscribe to receive messages published into that channel. Channel is just a string - but several symbols has special meaning - see special chapter to find more information about channels. The following options will affect channel behaviour:

  • watch – Centrifugo will additionally publish messages into admin channel (these messages can be visible in web interface messages tab). By default false. Note that this option must be used carefully in channels with high rate of new messages as admin client can not process all of those messages. Use this option in development or for channels with reasonable message rate.

  • publish – allow clients to publish messages into channels directly (from client side). Your application will never receive those messages. In idiomatic case all messages must be published by your application backend using Centrifugo API. But this option can be useful when you want to build something without backend-side validation and saving into database. This option can also be useful for demos and prototyping real-time ideas. Note that client can only publish data into channel after successfully subscribed on it. By default it's false.

  • anonymous – this option enables anonymous access (with empty user ID in connection parameters). In most situations your application works with authorized users so every user has its own unique id. But if you provide real-time features for public access you may need unauthorized access to some channels. Turn on this option and use empty string as user ID. By default false.

  • presence – enable/disable presence information. Presence is a structure with clients currently subscribed on channel. By default false – i.e. no presence information available for channels.

  • join_leave – enable/disable sending join(leave) messages when client subscribes on channel (unsubscribes from channel). By default false.

  • history_size – history size (amount of messages) for channels. As Centrifugo keeps all history messages in memory it's very important to limit maximum amount of messages in channel history to reasonable minimum. By default history size is 0 - this means that channels will have no history messages at all. As soon as history enabled then history_size defines maximum amount of messages that Centrifugo will keep for each channel in namespace during history lifetime (see below).

  • history_lifetime – interval in seconds how long to keep channel history messages. As all history is storing in memory it is also very important to get rid of old history data for unused (inactive for a long time) channels. By default history lifetime is 0 – this means that channels will have no history messages at all. So to get history messages you should wisely configure both history_size and history_lifetime options.

  • recover (new in v1.2.0) – boolean option, when enabled Centrifugo will try to recover missed messages published while client was disconnected for some reason (bad internet connection for example). By default false. This option must be used in conjunction with reasonably configured message history for channel i.e. history_size and history_lifetime must be set (because Centrifugo uses channel message history to recover messages). Also note that note all real-time events require this feature turned on so think wisely when you need this. See more details about how this option works in special chapter.

  • history_drop_inactive (new in v1.3.0) – boolean option, allows to drastically reduce resource usage (engine memory usage, messages travelling around) when you use message history for channels. In couple of words when enabled Centrifugo will drop history messages that no one needs. Please, see issue on Github to get more information about option use case scenario and edge cases it involves.

Let's look how to set all of these options in config:

{
    "secret": "very-long-secret-key",
    "connection_lifetime": 0,
    "anonymous": true,
    "publish": true,
    "watch": true,
    "presence": true,
    "join_leave": true,
    "history_size": 10,
    "history_lifetime": 30,
    "recover": true
}

And the last channel specific option is namespaces. namespaces are optional and if set must be an array of namespace objects. Namespace allows to configure custom options for channels starting with namespace name. This provides a great control over channel behaviour.

Namespace has a name and the same channel options (with same defaults) as described above.

  • name - unique namespace name (name must must consist of letters, numbers, underscores or hyphens and be more than 2 symbols length i.e. satisfy regexp ^[-a-zA-Z0-9_]{2,}$).

If you want to use namespace options for channel - you must include namespace name into channel name with : as separator:

public:messages

gossips:messages

Where public and gossips are namespace names from project namespaces.

All things together here is an example of config.json which includes registered project with all options set and 2 additional namespaces in it:

{
    "secret": "very-long-secret-key",
    "connection_lifetime": 0,
    "anonymous": true,
    "publish": true,
    "watch": true,
    "presence": true,
    "join_leave": true,
    "history_size": 10,
    "history_lifetime": 30,
    "namespaces": [
        {
          "name": "public",
          "publish": true,
          "presence": true,
          "join_leave": true,
          "anonymous": true,
          "history_size": 10,
          "history_lifetime": 30,
          "recover": true
        },
        {
          "name": "gossips",
          "watch": true
        }
    ]
}

Channel news will use global project options.

Channel public:news will use public namespace's options.

Channel gossips:news will use gossips namespace's options.