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 secondary instance fails, other instances remain available with a limited impact (see "Limitations" for details). In case of secondary server failure, users are redirected (by a load balancer) to another instance 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 previously 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 is configured to be the primary server, all other instances are configured to be secondary instances.
Each instance can be connected to a different user-data store BUT the data stores are kept in sync by a third party system that guarantees minimal state drifts (sync delays) and automatic resolution of conflicted data.
Each instance can be connected to a different graph database cluster BUT clusters are kept in sync by a third party system that guarantees minimal state drift AND alternative IDs are configured correctly and identically on all instances AND the sourceKey of the data-source in each instance is set to the same value.
All instances are 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).
All instances have identical configurations, except for: the flags for primary/secondary, the SQL database settings, the data-source settings, and the auth server settings.

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

The primary instance is set manually via its configuration file in linkurious/data/config/production.json .
When a user switches an 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):

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 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 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 does the feature works" section).
3. dataSources.*.graph.url.username/pasword can be set to a different server (if sync is guaranteed AND alternative IDs are correctly configured, see "How does the feature works" section).
4. access.saml2/oauth2 can be set to a different server if the backing directory contains the same accounts (see "How does the feature works" section).

When updating the Linkurious Enterprise cluster:

All instances must be stopped, then the primary instance must be configured and started.
Once the primary instance is started, all the secondary instances can be configured and restarted.
The global configuration of Linkurious Enterprise 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 need to set the same value on all instances manually).

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