Deploying on premise: Cluster mode

Linkurious Enterprise supports a cluster deployment mode which allows horizontal scaling and high availability. In cluster mode, one server instance is the "primary" and one or more instances are "secondary".

When a primary instance fails, its users are redirected (by a load balancer) to secondary instances, with a limited impact (see "limitations" for details).

When a secondary instance fails, its users are redirected (by a load balancer) to other instances in the cluster, where they can find their working objects (i.e., visualizations, queries, alerts, cases, etc.) as they last saved on the instance they were working on.

Several Linkurious Enterprise instances are deployed on different servers with the following cluster configuration:
```
"cluster": {
    "enabled": boolean,
    "mode": "primary" | "secondary",
    "maxDriftMs": number
}
```
- enabled: Whether cluster mode is enabled or disabled.
- mode: Whether the instance is a primary or a secondary one.
- maxDriftMs(default: 900000, i.e., 15 minutes): Time taken by the primary instance to schedule/unschedule alerts created/updated by secondary instances, send email notifications and webhooks generated by the secondary instances and for the caches on different instances in the cluster to be cleared.
Exactly one instance must be configured to be the primary instance, all other instances must be configured as secondary instances.
Each instance can be connected to a different user-data store BUT the data-stores must be kept in sync¹ (e.g., using MySQL NDB Cluster).
Each instance can be connected to a different graph database BUT the graph databases must be kept in sync¹ (e.g., using Neo4j clustering).
Each instance can be connected to a different Elasticsearch server BUT the servers must be kept in sync¹ (e.g., using a distributed Elasticsearch setup).
All instances must be configured with the same authentication directory, regardless of authentication method (e.g., they are configured to different SAML2 servers BUT all SAML2 servers contain the same user directory).
If Entity Resolution is used, then, all instances must be connected to the same Entity Resolution server.
All instances must have identical configurations, except for:
- the cluster mode (primary/secondary),
- the user-data store settings,
- the data-source settings,
- the authentication server details.

¹ Synchronization of servers must be done in a way that guarantees minimal state drifts (i.e., lower than the configured maxDriftMs), and automatic resolution of data conflicts.

When Linkurious Enterprise is deployed in cluster mode, the following limitations apply:

The deployment of a cluster and the number of instances in the cluster are bounded by license agreements. If you are not sure about the limits applied to your project, please get in touch with your point of contact.
The primary instance is set manually via its configuration file in linkurious/data/config/production.json.
When users switch instance, they may need to re-authenticate on the target instance.
The following features are disabled on secondary instances, so when the primary Linkurious Enterprise instance fails, they will be paused until the primary instance is restored (see "Updating in cluster mode" section):
The following actions can only be done by a user connected to the primary server:
- Launching Entity resolution detection
- Launching a manual Elasticsearch index refresh
Direct or indirect file modifications in the application data folder are not automatically synchronized and must be kept in sync manually. Common (but not exhaustive) examples are:
- The global configuration (as well as the manager.json and logger.json configuration files) must not be modified in ways that will make the configuration of different instances inconsistent (i.e., if you want to change a value in the global configuration, you must set the same value on all instances manually).
- Additional Certification Authorities should be kept aligned on all the instances.
- When a new plugin is deployed, it must be deployed on all the instances.
- When a new custom node icon is added, it must be added on all the instances.

Cluster mode is designed to be used with a load-balancer (e.g. HAProxy or nginx). The load-balancer is responsible for redirecting queries from end-users to currently available servers in the cluster.

In a typical load-balancer configuration, you would expose the cluster as cluster.my-domain.org and have several servers in the cluster (e.g. primary.my-domain.org, secondary-1.my-domain.org and secondary-2.my-domain.org) handle the traffic. When the server at secondary-1.my-domain.org becomes unavailable, the load-balancer redirects users working on this server to one of the available servers.

You must use a load-balancer that supports session persistence to make sure that end-users are consistently redirected to the same server during their work (see this example using nginx or this example using HAProxy).

Example nginx configuration (see details in the nginx documentation):

# Define the upstream group for your Linkurious Enterprise instances
upstream linkurious_backend {
    # Selects a server randomly for each request (respecting sticky session)
    random;

    # --- Sticky Sessions via Cookies ---
    # srv_id: name of the cookie
    # expires=2h: cookie lifetime
    # domain: scope of the cookie
    # path=/: cookie applies to the whole site
    # httponly: prevents client-side script access
    sticky cookie srv_id expires=2h domain=cluster.my-domain.org path=/ httponly ;

    # --- Backend Servers ---
    # max_fails=3: Consider server down after 3 consecutive failed attempts.
    # fail_timeout=30s: Mark the server down for 30 seconds before retrying.
    server primary.my-domain.org:80 max_fails=3 fail_timeout=30s;
    server secondary-1.my-domain.org:80 max_fails=3 fail_timeout=30s;
    server secondary-2.my-domain.org:80 max_fails=3 fail_timeout=30s;
}

server {
    listen 80;
    server_name cluster.linkurious.org;

    # --- Location Block for Proxying ---
    location / {
        # Pass requests to the upstream group defined above
        proxy_pass http://linkurious_backend;
    }
}

Install and configure the primary instance (the data-sources must be set up and have connected successfully at least once so that the sourceKey field is set in each dataSource.* configuration entry).
To create the configuration of secondary instances, copy the configuration file of the primary instance and change the following field:
1. cluster.mode must be set to "secondary".
2. db can be set to a different SQL server (if sync is guaranteed, see "How it works" section).
3. dataSources.*.graph.url/username/password can be set to a different server (if sync is guaranteed, see "How it works" section).
4. access.saml2/oauth2 can be set to a different server if the backing directory contains the same accounts (see "How it works" section).
Ensure that application data file changes are kept aligned across cluster instances (see "limitations" for details).

When updating the Linkurious Enterprise cluster:

All instances in the cluster must be stopped;
Then, the primary instance must be updated and restarted;
Then, all the secondary instances must be updated and restarted.

Previous Next

Deploying on premise: Cluster mode

How it works

Limitations

How to configure cluster mode

Setting up the load-balancer

Setting up Linkurious Enterprise

Updating in cluster mode