Failover Architecture

OptimiDoc achieves high availability by running several server nodes against one shared SQL Server database. All server nodes are active and can serve the web console, API, print release and scan traffic; a load balancer or DNS decides which node a client reaches. This reference explains how the cluster is structured, what the "master" role does, how nodes stay in sync, and what has to be in place for clean failover.

Why Failover?

Where print and scan services are business-critical, a single server is a single point of failure: if it goes down, users cannot release jobs, scan, or authenticate at devices. Running two or more OptimiDoc server nodes against a shared, highly-available database removes that single point of failure and lets you take a node out of service for maintenance without an outage.

The OptimiDoc Cluster Model

OptimiDoc does not have separate "active-passive" and "active-active" product modes. The model is always the same: multiple active server nodes sharing one database. How clients reach them is your choice — a load balancer, DNS round-robin, or a single DNS name you fail over manually.

                 ┌────────────────────────┐
                 │  Load balancer / DNS   │  ◄── clients & devices
                 └───────────┬────────────┘
              ┌──────────────┼──────────────┐
              │              │              │
      ┌───────┴──────┐┌──────┴───────┐┌─────┴────────┐
      │  Server 1    ││  Server 2    ││  Server 3    │
      │ (master)     ││              ││              │
      └───────┬──────┘└──────┬───────┘└─────┬────────┘
              └──────────────┼──────────────┘
                    ┌─────────┴─────────┐
                    │  Shared SQL Server │  (HA: Always On, FCI, Azure SQL)
                    └───────────────────┘

Every server node registers itself in the shared database on start-up (identified by its hostname / IIS binding) and refreshes a last action timestamp as it runs, so the cluster knows which nodes are currently alive. A node that has not checked in recently is treated as inactive. You can review all nodes — both Server nodes and any PrintingNode entries — under Diagnostics > Cluster Nodes.

Note the distinction: server nodes provide the highly-available console and processing described here; printing nodes are lightweight local print entry points and are not console failover targets. See Print Nodes Configuration.

The Master Role

Although every server node handles user traffic, some background responsibilities must run in exactly one place so they do not execute in duplicate across the cluster. These run only on the master node:

• Scheduled tasks — automatic reports and other timed jobs.

• Device monitoring — polling devices for status and supplies.

• Mailbox polling — collecting mail for print-by-email.

Master selection is automatic: the first server node becomes master, and if the master stops checking in, another active server node promotes itself on its next refresh. An administrator can also force the role with Set as Master in Diagnostics > Cluster Nodes (available on server nodes only). Because these are background duties, losing the master briefly delays scheduled work but does not stop users releasing print jobs or scanning on the remaining nodes.

Shared Database Requirement

All server nodes must reach the same SQL Server database, which holds users, devices, rules, job metadata and queue state, audit logs and reporting data, and (because OptimiDoc stores session state in the database) user sessions. Since sessions are database-backed, a user redirected to a different node keeps their session — no sticky sessions are required at the load balancer.

For genuine end-to-end failover the database itself should be highly available:

For smaller environments, a single reliable SQL Server with regular backups may be sufficient — but the database is then the single point of failure.

Configuration Convergence

Nodes do not share a config file; instead each node tracks timestamps for its rules, general configuration and IPP queue state, and pulls the freshest version from its peers so the cluster converges automatically. In particular, IPP queue attribute sets are pulled server-to-server at start-up and whenever a change is signalled, so a driverless-print change made on one node propagates to the others (and onward to printing nodes). This means you administer rules, settings and print queues from any node and the rest catch up without manual copying.

Joining a New Node When Encryption Is Enabled

OptimiDoc encrypts stored credential and destination secrets with a data key that is wrapped by a Master Encryption Key (MEK), and the MEK is protected with Windows DPAPI bound to the local machine. This creates a bootstrap problem for a brand-new server joining an existing cluster: the fresh machine has no MEK, so it cannot even decrypt the stored admin password to log in, let alone call the admin-protected key-exchange endpoint.

OptimiDoc resolves this with cluster-peer bootstrap endpoints that are authorised by peer IP rather than by an admin session. A new node asks an existing node to perform the login on its behalf and to release the MEK, after which the new node stores the MEK under its own machine's DPAPI and is fully operational. This happens as part of joining the cluster; no manual key handling is required as long as an existing cluster node is available. For replacing a standalone server (no surviving peer), use the recovery-key flow described in Migration to a New Server.

File Storage and the Shared Spooler

Print job spool files live on disk. By default each node keeps its own spool and, when a job needs to be released or previewed from a different node, that node fetches the file from the node that received it. Two approaches make spool files available cluster-wide:

• Shared spooler (recommended for clusters). Point all server nodes at a common spool location (for example a UNC share) and enable Use shared spooler under Settings > Print Settings. OptimiDoc then treats any server node's spool as locally readable, so any node can release any job directly.

• Replicated storage. Alternatively, replicate the spool directories (e.g. DFS Replication). Note that replication latency can briefly delay job availability after failover.

Ensure the shared storage itself is resilient (redundant NAS, DFS, or an HA file cluster).

Local DNS vs Cluster Address

Under Settings > Cluster Configuration each node has two address concepts:

• Cluster address — the DNS name clients and devices use to reach the cluster (often a load-balancer VIP or round-robin name).

• Local DNS — this node's own directly-resolvable name.

Self-referencing callbacks — scan delivery, e-mail links, print previews — use the Local DNS so a node calls itself rather than bouncing back through the cluster name to a possibly different node. Setting Local DNS correctly on each node avoids subtle cross-node routing issues in a load-balanced cluster.

Reaching the Cluster: DNS and Load Balancers

• Load balancer (recommended). Add all server nodes as backends and health-check each node's status endpoint. OptimiDoc exposes a simple status endpoint (Api/Status) that returns ok when the application is up; a node failing the check is removed from rotation and re-added when it recovers.

• DNS failover. For deployments without a load balancer, use a short DNS TTL and repoint the OptimiDoc hostname to a healthy node when the current one fails (manually or via a DNS health-check service).

Automatic Recovery

When a failed server node comes back online it reconnects to the shared database, refreshes its cluster registration, pulls any rules/configuration/IPP changes it missed, re-promotes to master if no master is currently active, and — behind a load balancer — is re-added to rotation once it passes health checks. No manual intervention is required, though it is wise to review the recovered node's logs for the root cause.

Failover Checklist

In Summary

OptimiDoc high availability means several active server nodes on one shared, ideally-HA database, reached through a load balancer or DNS. Exactly one node is master and runs the singleton background duties (scheduling, monitoring, mailbox polling), with automatic hand-over if it fails. Nodes converge their rules, configuration and IPP queues by pulling from peers, sessions live in the database so no sticky sessions are needed, and a shared spooler (or replicated storage) makes jobs releasable from any node. The step-by-step UI for adding and managing nodes lives on the Cluster Configuration settings page.

Related articles

• Cluster Configuration

• Print Nodes Configuration

• Migration to a New Server

• Cluster and Failover Issues

• Advanced Configuration