Skip to main content
Version: 10.0

Cluster configuration (cluster.json)

This page describes the structure, attributes, and interaction of the configuration in cluster.json for operating the webPDF Server in a clustered environment. Alternatives using environment variables are also explained.

info

In SINGLE mode, the cluster.json file is not required.

Purpose​

With cluster.json, you control whether a server node runs as a standalone instance (SINGLE) or within a cluster (CLUSTER), which role the node assumes (COORDINATOR/MEMBER), under which cluster name it operates (name), how it is identified (nodeName), how cluster communication is secured (secretKey), how strictly join errors are handled during startup (stopOnError), and how long to wait at startup (connectTimeout).

  • The cluster name (name, sometimes referred to as clusterName) must be a unique identifier for the cluster.
  • The node name (nodeName) must be a unique identifier for each node.

Structure​

The cluster.json is a single JSON object with the following attributes:

  • mode: string
  • role: string
  • name: string
  • nodeName: string
  • secretKey: string
  • stopOnError: boolean
  • connectTimeout: number (milliseconds)
  • namespace: object (optional)
  • configuration: object (optional)

Attributes​

mode​

  • Meaning: Switches between standalone and cluster mode.
  • Valid values:
    • SINGLE – single node (default)
    • CLUSTER – clustered operation
  • Behavior:
    • SINGLE: Clustering is disabled; cluster.json may be omitted.
    • CLUSTER: Clustering is enabled; further cluster attributes apply (see below).

role​

  • Meaning: The node’s function within the cluster.
  • Valid values:
    • COORDINATOR – initializes the cluster and distributes configuration.
    • MEMBER – joins an existing cluster (default).
  • Applies only when mode = CLUSTER.

name​

  • Meaning: Logical name of the cluster.
  • Requirements:
    • Must be a unique identifier across all clusters that might be reachable in your environment(s).
  • Behavior:
    • COORDINATOR: Creates/initializes a cluster under this name.
    • MEMBER: Attempts to join the cluster with this name.
  • Default: "" (set explicitly in cluster mode).
  • Recommendations:
    • Use a stable, descriptive, and unique value (for example, a namespaced name like prod/eu-west/webpdf or a UUID if in doubt).

nodeName​

  • Meaning: Display name/identifier of this node.
  • Requirements:
    • Must be a unique identifier per node within the cluster.
  • Behavior: If nodeName is empty or not set, the host name is used. If no host name is available at runtime, a random UUID may be generated.
  • Default: "" (host name will be used).
  • Recommendations:
    • Use clear, unique names for monitoring and operations, e.g., coordinator-1, member-1.

secretKey​

  • Meaning: Shared key for encrypting intra-cluster communication.
  • Requirements:
    • 64-character hexadecimal string (256-bit).
    • All nodes in the same cluster must use exactly the same key.
  • Security: Keep it secret; do not commit it to version control.

→ Complete Secret Key Documentation - Detailed guide on generation, distribution, security, and rotation

stopOnError​

  • Meaning: How to handle errors during cluster join/startup.
  • Behavior:
    • true (default): Node continues to start even if such an error occurs.
    • false: Startup is aborted in case of such errors.
  • Trade-off: Availability (true) vs. strictness/consistency (false).

connectTimeout​

  • Meaning: Wait time in milliseconds while joining/starting in cluster mode (e.g., waiting for the COORDINATOR).
  • Type: number (milliseconds)
  • Default: 60000
  • Recommendation: Increase in slower environments.

namespace​

  • Meaning: Namespace settings used to create prefixes (e.g., Redis hash keys) or default names (e.g., S3 buckets) for this cluster.
  • Type: object (optional)
  • Structure:
    • org: string – Optional organization/vendor identifier (default: "webpdf")
    • app: string – Application identifier (required, default: "webpdf")
    • env: string – Optional environment name (e.g., "prod", "dev")
    • region: string – Optional region identifier (e.g., "eu1")
    • cluster: string – Optional cluster discriminator for blue/green or canary deployments (e.g., "blue")
    • version: string – Key schema version (default: "v10.0")
  • Purpose: Provides structured namespace components for building Redis/S3 prefixes and ensuring logical separation of resources across different environments, regions, and deployment strategies.

configuration​

  • Meaning: Configuration settings for how cluster nodes receive their configuration.
  • Type: object (optional)
  • Structure:
    • source: string – Defines where nodes receive configuration from
      • COORDINATOR (default) – Configuration is provided by the coordinator to all nodes
      • NODE – Each node uses its local configuration settings
  • Behavior:
    • COORDINATOR: All member nodes receive configuration from the coordinator node, ensuring consistency across the cluster.
    • NODE: Each node uses its own local configuration, allowing for node-specific settings.
caution

Ensure both name (cluster identifier) and nodeName (node identifier) are unique in their respective scopes. Duplicate values can lead to unintended joins or operational ambiguity.

Examples​

{
  "mode": "SINGLE"
}
tip

Generate a 256-bit key for secretKey by creating 32 random bytes and encoding them in hexadecimal (64 characters). Use openssl rand -hex 32 or see the Secret Key Guide for more methods.

Environment variables​

All settings can also be provided via environment variables as an alternative to cluster.json.

  • Notation: Always UPPERCASE
  • Prefix: WEBPDF_CLUSTER_SETTINGS_
  • Dots in the logical prefix are replaced by underscores.
  • Attribute mapping:
    • mode → WEBPDF_CLUSTER_SETTINGS_MODE
    • role → WEBPDF_CLUSTER_SETTINGS_ROLE
    • name → WEBPDF_CLUSTER_SETTINGS_NAME
    • nodeName → WEBPDF_CLUSTER_SETTINGS_NODE_NAME
    • secretKey → WEBPDF_CLUSTER_SETTINGS_SECRET_KEY
    • stopOnError → WEBPDF_CLUSTER_SETTINGS_STOP_ON_ERROR
    • connectTimeout → WEBPDF_CLUSTER_SETTINGS_CONNECT_TIMEOUT (milliseconds)
    • namespace.org → WEBPDF_CLUSTER_SETTINGS_NAMESPACE_ORG
    • namespace.app → WEBPDF_CLUSTER_SETTINGS_NAMESPACE_APP
    • namespace.env → WEBPDF_CLUSTER_SETTINGS_NAMESPACE_ENV
    • namespace.region → WEBPDF_CLUSTER_SETTINGS_NAMESPACE_REGION
    • namespace.cluster → WEBPDF_CLUSTER_SETTINGS_NAMESPACE_CLUSTER
    • namespace.version → WEBPDF_CLUSTER_SETTINGS_NAMESPACE_VERSION
    • configuration.source → WEBPDF_CLUSTER_SETTINGS_CONFIGURATION_SOURCE
note

If both cluster.json and environment variables are provided, environment variables usually take precedence.

Relation within the application​

  • Startup behavior:
    • mode = SINGLE: The server runs as a standalone instance; cluster.json is not required.
    • mode = CLUSTER:
      • role = COORDINATOR: The node initializes the cluster under name and distributes configuration.
      • role = MEMBER: The node attempts to join the cluster identified by name; wait time according to connectTimeout.
  • Uniqueness requirements:
    • The cluster name (name / clusterName) must be a unique identifier within the reachable network/domain to prevent unintended joins between distinct clusters.
    • The node name (nodeName) must be unique within the cluster to ensure unambiguous identification in logs, metrics, and administration tools.
  • Security: secretKey must be identical on all nodes to enable encrypted communication.
  • Robustness: stopOnError controls whether the node continues to start despite join errors.