Cluster Configuration

This section covers the configuration files required to set up and operate webPDF Server in cluster mode. Proper configuration of these files is essential for a functioning multi-node deployment.

Important

It is recommended to perform the (initial) configuration of the cluster via the Admin Portal.

Overview

webPDF Server cluster configuration consists of two main configuration files:

1. cluster.json – Defines cluster mode, node role, and cluster membership settings
2. provider.json – Configures storage providers for shared data across cluster nodes

Both configuration files work together to enable distributed operation of webPDF Server across multiple nodes.

Configuration Files

Cluster Configuration (cluster.json)

The cluster.json file controls fundamental cluster behavior:

• Cluster Mode – Whether the server runs as standalone (SINGLE) or in cluster mode (CLUSTER)
• Node Role – Whether the node is a COORDINATOR (manages cluster) or MEMBER (worker node)
• Cluster Identity – Cluster name and node name for identification
• Security – Secret key for encrypted communication between nodes
• Connection Settings – Timeouts and error handling during cluster join

→ Complete cluster.json Documentation

Quick Example

{
  "mode": "CLUSTER",
  "role": "COORDINATOR",
  "name": "webpdf-prod-cluster",
  "nodeName": "coordinator-1",
  "secretKey": "64-character-hexadecimal-key",
  "stopOnError": true,
  "connectTimeout": 60000
}

Provider Configuration (provider.json)

The provider.json file determines which storage backends are used for shared data:

• Document Storage – Where processed documents and metadata are stored
• File Storage – Where uploaded files are stored
• Session Storage – Where user session data is stored

Each storage type can use a different provider, allowing flexible architecture designs.

note

For some provider types, additional configuration files are required. See the Storage Providers Overview for details.

→ Complete provider.json Documentation

Quick Example

{
  "documentStorage": {
    "name": "REDIS",
    "checks": {"enabled": true, "interval": 5000}
  },
  "fileStorage": {
    "name": "MINIO",
    "checks": {"enabled": true, "interval": 10000}
  },
  "sessionStorage": {
    "name": "REDIS",
    "checks": {"enabled": true, "interval": 5000}
  }
}

Storage Providers

webPDF Server supports multiple storage provider types for cluster deployments:

Available Providers

Provider	Document Storage	File Storage	Session Storage	Best For
LOCAL	✓	✓	✓	Single-node only
REDIS	✓	✗	✓	In-memory cache
VALKEY	✓	✗	✓	In-memory cache (Redis-compatible alternative)
MINIO	✗	✓	✗	S3-compatible object storage
AZURE_BLOB	✗	✓	✗	Azure cloud storage
SMB	✗	✓	✗	Windows/NAS file shares
NFS	✗	✓	✗	NFS file share (via LOCAL provider)

tip

For cluster deployments, you must use distributed storage providers. The LOCAL provider only works for single-node installations.

→ Complete Storage Providers Overview

Recommended Cluster Configurations

Standard On-Premise Cluster

• Document Storage: REDIS or VALKEY
• File Storage: MINIO, SMB or NFS
• Session Storage: REDIS

Azure Cloud Cluster

• Document Storage: REDIS or VALKEY
• File Storage: AZURE_BLOB
• Session Storage: REDIS or VALKEY

AWS/S3-Compatible Cluster

• Document Storage: REDIS or VALKEY
• File Storage: MINIO (with S3 backend)
• Session Storage: REDIS or VALKEY

Configuration Workflow

Follow these steps to configure a webPDF Server cluster:

1. Plan Your Architecture

Before configuring, determine:

• Number of nodes (minimum 2)
• Which node will be the coordinator
• Storage backend choices (Redis/Valkey, MinIO/Azure/SMB)
• Network topology and security requirements

2. Set Up Storage Backends

Configure the required storage services:

• Redis/Valkey Server – For document and session storage
• MinIO/Azure/SMB/NFS – For file storage
• Verify connectivity from all cluster nodes

3. Configure Coordinator Node

On the designated coordinator node:

Create cluster.json:

{
  "mode": "CLUSTER",
  "role": "COORDINATOR",
  "name": "your-cluster-name",
  "nodeName": "coordinator-1",
  "secretKey": "generate-secure-64-char-hex-key",
  "stopOnError": true,
  "connectTimeout": 60000,
  "namespace": {
    "org": "your-org",
    "app": "webpdf",
    "env": "prod"
  }
}

Create provider.json:

{
  "documentStorage": {
    "name": "REDIS",
    "checks": {"enabled": true, "interval": 5000}
  },
  "fileStorage": {
    "name": "MINIO",
    "checks": {"enabled": true, "interval": 10000}
  },
  "sessionStorage": {
    "name": "REDIS",
    "checks": {"enabled": true, "interval": 5000}
  }
}

Create provider-specific configs:

• provider-redis.yaml – Redis connection details
• provider-redis.yaml – Redis connection details
• provider-minio.json – MinIO/S3 connection details

Secret Key

The secretKey is automatically generated by the coordinator during cluster creation via Admin Portal. For manual setup or key rotation, see the Secret Key Guide.

4. Configure Member Nodes

On each member node, create identical configuration with different node name:

cluster.json (member):

{
  "mode": "CLUSTER",
  "role": "MEMBER",
  "name": "your-cluster-name",
  "nodeName": "member-1",
  "secretKey": "same-64-char-hex-key-as-coordinator",
  "stopOnError": true,
  "connectTimeout": 60000
}

Note: provider.json and provider-specific configs are synchronized from the coordinator, but can be created manually as well.

5. Start Cluster

1. Start the coordinator node first
2. Verify coordinator is running and healthy
3. Start member nodes one by one
4. Verify each member successfully joins the cluster
5. Configure load balancer/gateway to distribute requests

6. Verify Configuration

After starting all nodes:

• Check cluster status in Admin Portal
• Verify all nodes are visible and active
• Test document processing across different nodes
• Verify session sharing works correctly
• Monitor storage provider health checks

Configuration Best Practices

Security

✓ Generate Strong Secret Keys

# Generate 256-bit (64 hex characters) secret key
openssl rand -hex 32

See Secret Key Guide for detailed generation methods, security best practices, and rotation procedures.

✓ Use Environment Variables for Secrets

export WEBPDF_CLUSTER_SETTINGS_SECRET_KEY="your-secret-key"

✓ Encrypt Storage Communication

• Use TLS for Redis connections
• Use HTTPS for MinIO/S3 connections
• Use SMBv3 encryption for SMB shares

Reliability

✓ Enable Health Checks

{
  "documentStorage": {
    "name": "REDIS",
    "checks": {
      "enabled": true,
      "interval": 5000
    }
  }
}

✓ Use Appropriate Timeouts

• Set connectTimeout based on network latency
• Consider slower networks (WAN, cloud)
• Typical values: 30000-120000 ms

✓ Plan for Failures

• Configure stopOnError based on requirements
• Test node failure scenarios
• Document recovery procedures

Consistency

✓ Identical Configuration

• All nodes must use the same cluster name
• All nodes must use the same secret key
• All nodes must point to the same storage backends

✓ Unique Node Names

• Each node must have a unique nodeName
• Use descriptive names: coordinator-1, member-1, member-2

✓ Version Compatibility

• All nodes must run the same webPDF version
• Upgrade all nodes together during maintenance windows

Troubleshooting

Cluster Configuration Issues

Node Cannot Join Cluster

Symptoms: Member node fails to connect to cluster

Check:

1. Cluster name matches on all nodes
2. Secret key is identical on all nodes
3. Coordinator node is running and accessible
4. Network connectivity between nodes
5. Firewall rules allow cluster communication

Configuration Sync Failures

Symptoms: Member nodes have outdated configuration

Check:

1. Coordinator is running and healthy
2. Network connectivity from members to coordinator
3. No configuration errors on coordinator
4. Restart member nodes to trigger re-sync

Provider Configuration Issues

Cannot Connect to Storage Provider

Symptoms: Errors connecting to Redis, MinIO, etc.

Check:

1. Storage backend is running and accessible
2. Credentials are correct in provider config files
3. Network connectivity from all nodes to storage
4. Health checks show provider status
5. Provider-specific logs for detailed errors

Provider Health Check Failures

Symptoms: Health checks report provider as unhealthy

Check:

1. Storage backend health and capacity
2. Network latency to storage backend
3. Adjust health check intervals if needed
4. Review storage backend logs

Common Mistakes

❌ Using LOCAL provider in clusters

• LOCAL provider does not share data between nodes
• Always use distributed providers (REDIS, MINIO, etc.)

❌ Different secret keys on nodes

• Nodes with different keys cannot communicate
• Verify key is identical on all nodes

❌ Mismatched cluster names

• Nodes with different cluster names won't join same cluster
• Check for typos in cluster name

❌ Missing provider configuration files

• Provider-specific configs must exist (e.g., provider-redis.json)
• Verify all required config files are present

Environment Variables

Both cluster and provider settings can be overridden via environment variables:

Cluster Settings

# Cluster mode and role
export WEBPDF_CLUSTER_SETTINGS_MODE=CLUSTER
export WEBPDF_CLUSTER_SETTINGS_ROLE=MEMBER

# Cluster identification
export WEBPDF_CLUSTER_SETTINGS_NAME=webpdf-prod
export WEBPDF_CLUSTER_SETTINGS_NODE_NAME=member-2

# Security
export WEBPDF_CLUSTER_SETTINGS_SECRET_KEY=your-secret-key

# Connection
export WEBPDF_CLUSTER_SETTINGS_CONNECT_TIMEOUT=60000

Provider Settings

# Provider selection
export WEBPDF_PROVIDER_SETTINGS_DOCUMENT_STORAGE_NAME=REDIS
export WEBPDF_PROVIDER_SETTINGS_FILE_STORAGE_NAME=MINIO
export WEBPDF_PROVIDER_SETTINGS_SESSION_STORAGE_NAME=REDIS

tip

Environment variables take precedence over configuration file values, making them ideal for containerized deployments.

Related Documentation

Configuration Files

• cluster.json Configuration – Complete cluster settings reference
• Secret Key Guide – Secret key generation and security
• provider.json Configuration – Complete provider settings reference

Storage Providers

• Storage Providers Overview – All available providers
• REDIS Provider – Redis document/session storage
• VALKEY Provider – Valkey document/session storage
• MINIO Provider – MinIO S3-compatible file storage
• AZURE_BLOB Provider – Azure Blob file storage
• SMB Provider – SMB/CIFS file storage
• NFS Provider – NFS file storage (via LOCAL provider with shared usage enabled)
• LOCAL Provider – Local filesystem (single-node only)

Cluster Setup

• Cluster Overview – Understanding cluster concepts
• Cluster Requirements – Prerequisites for cluster setup
• Cluster Setup Guide – Step-by-step setup instructions

Administration

• Admin Portal – Managing cluster via web interface
• Cluster Administration – Monitoring cluster status