> ## Documentation Index
> Fetch the complete documentation index at: https://syteca.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy Syteca in a Microsoft Failover Cluster

> Deploy the Syteca Application Server across Microsoft Failover Cluster nodes so a second instance takes over automatically if the active one fails, with no data loss or reinstallation.

High Availability mode runs the Syteca Application Server on two or more Microsoft Failover Cluster nodes. If the active Application Server stops for any reason, the Failover Cluster Manager starts the service on another node automatically. Clients and the Management Tool reconnect to the same address, and no data is lost.

This page covers the deployment end to end. Several steps are the standard Syteca installation procedures with cluster-specific differences, and those differences are what this page spells out.

> [!WARNING]
>
> **NOT AVAILABLE IN SAAS.** This deployment applies to **on-premises** installations only.

## How the pieces fit together

Clients and the Management Tool never connect to an individual node. They connect to the **cluster role's** name or IP address, and the cluster decides which node is serving it at any moment. Getting that address into the right field is the thread running through steps 6 to 9 below.

| Component | Where it runs |
| - | - |
| Application Server | Installed on every cluster node, running on one node at a time |
| Database | A single shared database that every node connects to |
| Binary data storage | A shared folder reachable from every node, or shared storage added to the cluster |
| Management Tool | A separate computer, pointed at the cluster role address |
| Clients | Pointed at the cluster role address |

> [!NOTE]
>
> Configure the database for high availability too. A clustered Application Server still has a single point of failure if the database behind it is standalone. See the Microsoft documentation on SQL Server failover cluster instances.

## Before you start

| Requirement | Notes |
| - | - |
| Every node runs the same Windows Server version | A mixed-version cluster is not supported. |
| Every node is joined to the same Active Directory domain | |
| The account creating the cluster is a domain user with local administrator rights on every node | |
| That account holds the **Create Computer objects** permission on the organizational unit | The cluster creates a computer object in the domain. |
| Two network interfaces on the storage server | Only if you intend to use Multipath I/O. |

For hardware sizing, supported operating systems, database versions, and runtime prerequisites, see [Application Server requirements](https://syteca.com/docs/get-started/requirements/application-server.md). For the ports the Application Server needs open, see [Network ports](https://syteca.com/docs/get-started/requirements/network-ports.md).

## The deployment, step by step

**1. Deploy the failover cluster**

Install the Failover Clustering feature on every node, validate the configuration, and create the cluster. See [1. Deploy the failover cluster](#1--deploy-the-failover-cluster).

**2. Add shared storage, if you need it**

Optional. Store binary data from Clients on a standalone storage server. See [2. Add shared storage](#2--add-shared-storage).

**3. Install the Application Server on every node**

The first instance creates or connects to the database. Every later instance connects to that same database. See [3. Install the Application Server on each node](#3--install-the-application-server-on-each-node).

**4. Configure each Application Server instance**

A registry value on the first node, and the master certificate on the others. See [4. Configure the Application Server instances](#4--configure-the-application-server-instances).

**5. Create the Application Server role in the cluster**

A Generic Service role, so the cluster watches the service and not just the node. See [5. Create the Application Server role](#5--create-the-application-server-role).

**6. Install the Management Tool**

Pointed at the cluster role address. See [7. Install the Management Tool](#7--install-the-management-tool).

**7. Activate serial keys**

From the node that currently owns the role. See [8. Activate serial keys](#8--activate-serial-keys).

**8. Install Clients**

Pointed at the cluster role address. See [9. Install Clients](#9--install-clients).

## 1. Deploy the failover cluster

### Install the Failover Clustering feature

Repeat this on every server that will be a cluster node.

**1. Open Add Roles and Features**

Start **Server Manager**, then on the **Manage** menu select **Add Roles and Features**.

**2. Work through the wizard**

Click **Next** on **Before you begin**. On **Select installation type**, choose **Role-based or feature-based installation**. On **Select destination server**, choose the server. Click **Next** through **Select server roles**.

**3. Select Failover Clustering**

On **Select features**, select **Failover Clustering**. To install the management tools as well, click **Add Features**, then **Next**.

**4. Install**

On **Confirm installation selections**, click **Install**, then **Close** when it finishes.

### Validate the configuration

**1. Open the Failover Cluster Manager**

Start **Server Manager** on a node where the feature is installed, then on the **Tools** menu select **Failover Cluster Manager**.

**2. Start the validation wizard**

In the **Actions** pane, select **Validate Configuration**, then click **Next** on **Before You Begin**.

**3. Add every node**

On **Select Servers or a Cluster**, enter the NetBIOS name or fully qualified domain name of each server you plan to add as a node. Click **Next**.

**4. Run the tests**

On **Testing Options**, select **Run all tests (recommended)**, then click **Next** through **Confirmation**.

**5. Read the results**

On **Summary**, click **Finish** if the configuration is suitable for clustering. If there are warnings or failures, select **View Report**. Fix the failures before continuing, and resolve the warnings where you can.

### Create the cluster

Do this once, on any one of the nodes.

**1. Start the Create Cluster wizard**

In the **Failover Cluster Manager**, in the **Actions** pane, select **Create Cluster**, then click **Next**.

**2. Add the nodes**

On **Select Servers or a Cluster**, enter each server's NetBIOS name or fully qualified domain name. Click **Next**.

**3. Name the cluster and give it an address**

On **Access Point for Administering the Cluster**, enter a **Cluster Name**. Select the check box next to each network to use for cluster management, then enter the IP address to assign to the cluster. Click **Next**.

**4. Create it**

Click **Next** to create the cluster, then confirm on the **Summary** page that it was created.

> [!NOTE]
>
> The cluster is created once, from one node. To manage it from the other nodes afterwards, use **Connect to Cluster** in the Failover Cluster Manager and give the cluster name or IP address.

> [!TIP]
>
> Microsoft's [failover clustering documentation](https://docs.microsoft.com/en-us/windows-server/failover-clustering/failover-clustering-overview) covers the cluster itself in far more depth than this page does.

## 2. Add shared storage

This step is optional. If binary data from Clients needs to live on a standalone storage server, for example because of its volume, add shared storage to the cluster. One way is iSCSI with Microsoft Failover Clustering, which runs to four stages: install the iSCSI Target Server role on the storage server, create an iSCSI virtual disk, connect the disk to every cluster node, then add the disk to the cluster.

See [Shared storage high availability](https://syteca.com/docs/administration/deployment/shared-storage-ha.md) for the full procedure.

> [!NOTE]
>
> Multipath I/O requires two network interfaces on the standalone storage server.

## 3. Install the Application Server on each node

Install in two stages: the first instance, then every subsequent one.

| Stage | What differs |
| - | - |
| **First instance** | Select an existing database or create a new one. |
| **Every later instance** | Select the **same database** the first instance uses. |

Follow the standard procedure in [Install the Application Server](https://syteca.com/docs/administration/deployment/install-application-server.md), with these cluster-specific points:

* **Binary data path.** To store binary data in a shared folder, give the path as `\\<computer IP>\<folder path>` or `\\<computer name>\<folder path>`. If you added shared storage to the cluster in step 2, give the shared storage path instead, for example `D:\`.

  > [!WARNING]
  >
  > The path must be reachable from **every** cluster node. A path that resolves on only one node produces a cluster that fails over into a broken state.

* **Master certificate.** Back up the master certificate from the **first** instance only. You import it onto the other nodes in step 4. See [Master certificate](https://syteca.com/docs/administration/security/master-certificate.md).

* **Firewall.** The Application Server executable needs to accept TCP connections on the ports listed in [Network ports](https://syteca.com/docs/get-started/requirements/network-ports.md). These rules are added automatically if Windows Firewall is enabled during installation.

## 4. Configure the Application Server instances

Once the Application Server is installed on every node, configure the instances. The first node and the rest are configured differently.

### On the first instance

**1. Stop the service**

Stop the `EkranServer` service.

**2. Check the registry value**

Open the Windows Registry Editor and select the `HKEY_LOCAL_MACHINE\SOFTWARE\EkranSystem` key.
If there is no key `UseLegacyHwid` with the value `0` then create a new one using Select **Edit > New > DWORD Value** and add a value named..

**3. Start the service**

Start the `EkranServer` service.

### On every other instance

**1. Stop the service**

Stop the `EkranServer` service.

**2. Replace the master certificate**

Delete the existing `EkranMasterCertificate` from the Windows certificate store, then import the one you backed up from the first instance. See [Master certificate](https://syteca.com/docs/administration/security/master-certificate.md).

> [!WARNING]
>
> **Do not start the service on the other nodes.** The Failover Cluster Manager starts it when it needs to, and starting it by hand puts two Application Servers on the same database at once.

## 5. Create the Application Server role

A cluster watches nodes, not services. Creating a Generic Service role for the Application Server means the cluster also watches the service itself, and fails over when the service stops even though its node is still up.

**1. Open Configure Role**

On the first node, start **Server Manager**, then **Tools > Failover Cluster Manager**. Expand the cluster, select **Roles**, and in the **Actions** pane click **Configure Role**.

**2. Select Generic Service**

On **Select Role**, click **Generic Service**, then **Next**.

**3. Select the service**

On **Select Service**, select `EkranServer`.

**4. Define the client access point**

On **Client Access Point**, enter a **Name** for the role and its IP address. **This is the address Clients and the Management Tool will use.** Note it down: you need it in steps 7 and 9.

NetBIOS names are limited to 15 characters.

**5. Replicate the registry settings**

On **Replicate Registry Settings**, click **Add** and specify the registry key `SOFTWARE\EkranSystem`.

**6. Finish**

Work through to the confirmation step and click **Finish**.

### Set the failover thresholds

**1. Open the role's properties**

In the Failover Cluster Manager, select **Roles**, select the role you created, and in the **Actions** pane select **Properties**.

**2. Set the thresholds**

On the **Failover** tab, set **Maximum failures in the specified period** and **Period (hours)**, then click **OK**.

## 6. Verify failover

Test this before you put the deployment into service, not after.

**1. Move the role**

In the Failover Cluster Manager, expand the cluster, click **Roles**, select the Application Server role, and click **Move** in the **Actions** pane.

**2. Pick a destination node**

Click **Select Node**, then choose another node that has the Application Server installed, and click **OK**.

**3. Confirm the handover**

The **Owner Node** column changes to the node you selected. The service stops on the previous node and starts automatically on the new one.

> [!TIP]
>
> The role reports **Running** on the new owner node, and Clients and the Management Tool stay connected through the role address.

## 7. Install the Management Tool

Install the Management Tool on a separate computer, following [Install the Management Tool](https://syteca.com/docs/administration/deployment/install-management-tool.md).

On the **Connection Settings** page, in the **Server address** box, enter the name or IP address **defined for the Application Server role in step 5**, not the address of any individual node.

> [!NOTE]
>
> You can install the Management Tool on several computers. Give each one the same role name or IP address.

## 8. Activate serial keys

Activate serial keys the usual way, as described in [Activate a serial key](https://syteca.com/docs/administration/licensing/activate-serial-key.md). Two cluster-specific points:

* **Online activation** needs an active internet connection from the cluster.
* **Offline activation** needs the unique identifier generated on the node that **currently owns the Application Server role** and is running the service. Generating it on a different node produces an identifier the license site will not match.

## 9. Install Clients

Install Clients following the procedure for each platform: [Windows](https://syteca.com/docs/administration/clients/install-windows.md), [macOS](https://syteca.com/docs/administration/clients/install-macos.md), or [Linux](https://syteca.com/docs/administration/clients/install-linux.md).

Wherever the procedure asks for the Server address, give the name or IP address defined for the Application Server role in step 5.

| Installation method | Where the role address goes |
| - | - |
| Remote installation through the Management Tool | **Server name/IP** on the **Client configuration** page |
| Generated installation package | **Server name/IP** on the **Generate Installation Package** page |
| Local installation without an `.ini` file | The Server address field in the local installation window |
| macOS | `./install.sh <cluster_role_name or IP address> <server_port>` |
| Linux | `$ sudo ./install.sh <cluster_role_name or IP address> <server_port>` |

## What happens when a node fails

If the Application Server service on the owner node fails, or the node itself fails, the Failover Cluster Manager moves the role to the next available node and starts the service there. Data recorded through the failed node remains available, because every node works against the same database and the same binary storage.

No manual recovery is required to restore service. Investigate the failed node afterwards and repair it so it can serve as a backup again.

## Update the Application Server in a cluster

An Application Server spread across cluster nodes is updated with the Windows **Cluster-Aware Updating (CAU)** feature, which updates clustered servers in turn while keeping the role available.

| Mode | Where it is configured | How updates run |
| - | - | - |
| **Self-updating** | On the cluster nodes | On a schedule, and on demand when an administrator triggers one |
| **Remote-updating** | On a separate computer, the Update Coordinator | On demand, triggered from that computer |

### Prerequisites

**Failover Clustering Tools** must be installed: on every node for self-updating mode, or on the Update Coordinator computer for remote-updating mode. Install them with **Add Roles and Features**, selecting **Failover Clustering** on the **Select features** page and clicking **Add Features** when prompted for the management tools.

**A Server Message Block (SMB) file share** holds the new Application Server versions, and must be reachable from every node and from the Update Coordinator.

> [!WARNING]
>
> The account used for updating has to be a local administrator on the SMB server. If your security policy forbids that, configure the account with the required permissions following Microsoft's [CAU plug-in documentation](https://docs.microsoft.com/en-us/windows-server/failover-clustering/cluster-aware-updating-plug-ins#to-configure-a-user-account-on-the-smb-server).

### Configure the SMB file share

**1. Create the shared folder**

Create a shared folder on the SMB server.

**2. Copy the CAU configuration file**

Copy `DefaultHotfixConfig.xml` into the shared folder. It is found at `%systemroot%\System32\WindowsPowerShell\v1.0\Modules\ClusterAwareUpdating\` on the computer where the CAU tools are installed.

**3. Create the folder structure**

In the shared folder, create a subfolder named `CAUHotfix_All`. Inside it, create a subfolder to hold the Application Server files:

```text theme={"system"}
\\FileServer\SytecaServerUpdates\
    DefaultHotfixConfig.xml
    CAUHotfix_All\
        SytecaServer\
```

**4. Edit the configuration file**

In `DefaultHotfixConfig.xml`, add a `FolderRules` section after `DefaultRules`. The `Folder name` parameter must match the subfolder you created inside `CAUHotfix_All`:

```xml theme={"system"}
<?xml version="1.0" encoding="utf-8"?>
<root>
    <DefaultRules>
        . . .
    </DefaultRules>
    <!-- Rule to install Syteca Application Server updates -->
    <FolderRules>
        <!-- Folder name must be as the one in "CAUHotfix_All" -->
        <Folder name="SytecaServer" alwaysReboot="false">
            <Template path="$update$" parameters="/S"/>
            <ExitConditions>
                <Success>
                    <ExitCode code="0"/>
                </Success>
            </ExitConditions>
        </Folder>
    </FolderRules>
</root>
```

**5. Optionally enable SMB encryption**

On the SMB server, run:

```powershell theme={"system"}
Set-SmbShare <ShareName> -EncryptData $true
```

> [!NOTE]
>
> The folder name in `CAUHotfix_All` and the `Folder name` value in `DefaultHotfixConfig.xml` are yours to choose, but they must be identical. The example above uses `SytecaServer` for both.

### Self-updating mode

**1. Open Cluster-Aware Updating**

Start **Server Manager** on any cluster node, select **Tools > Failover Cluster Manager**, then in the **Actions** pane click **More actions** and select **Cluster-Aware Updating**.

**2. Start the configuration wizard**

In the **Cluster Actions** pane, select **Configure cluster self-updating options**, then click **Next** on **Getting Started**.

**3. Add the CAU clustered role**

On **Add Clustered Role**, select **Add the CAU clustered role, with self-updating mode enabled, to this cluster**, then click **Next**.

**4. Set the schedule**

On **Self-updating schedule**, specify the frequency, date, and time.

**5. Set the plug-in**

On **Advanced Options**, set **CauPluginName** to `Microsoft.HotfixPlugin`, then click **Next**.

**6. Point CAU at the share**

On **Additional Options**, enter the path to the root folder holding the update files and wait for it to be verified. Select **Require SMB encryption in accessing the hotfix root folder** if you enabled SMB encryption, and select **Disable check for administrator access to the hotfix root folder and configuration file**. Click **Next**.

**7. Apply**

On **Confirmation**, click **Apply**.

Once self-updating is configured and a new Application Server version is uploaded to the shared folder, installation starts automatically on schedule. To run it immediately, use **Apply updates to this cluster**.

### Remote-updating mode

Upload the new Application Server version to the shared folder, then run this on the Update Coordinator computer:

```powershell theme={"system"}
Invoke-CauRun -ClusterName <cluster_name> -CauPluginName Microsoft.HotfixPlugin -CauPluginArguments @{ 'HotfixRootFolderPath' = <path_to_the_share>; 'RequireSmbEncryption' = 'True'; 'DisableAclChecks' = 'True'; 'HotfixConfigFileName' = 'DefaultHotfixConfig.xml' } -EnableFirewallRules -Force
```

> [!TIP]
>
> Microsoft's [Cluster-Aware Updating documentation](https://docs.microsoft.com/en-us/windows-server/failover-clustering/cluster-aware-updating) covers the feature itself, including its scheduling and reporting options.

## Related

> [card] [High availability overview](https://syteca.com/docs/administration/deployment/high-availability.md)
>
> The high availability options and how to choose between them.

> [card] [Standard vs HA modes](https://syteca.com/docs/administration/deployment/standard-vs-ha-modes.md)
>
> What changes when a deployment moves to high availability.

> [card] [Shared storage high availability](https://syteca.com/docs/administration/deployment/shared-storage-ha.md)
>
> iSCSI shared storage and storage replication for binary data.

> [card] [Load balancing installation](https://syteca.com/docs/administration/deployment/load-balancing-installation.md)
>
> Adding Application Server instances behind a load balancer.

> [card] [Master certificate](https://syteca.com/docs/administration/security/master-certificate.md)
>
> Back up, import, and reissue the certificate every node shares.

> [card] [Update best practice](https://syteca.com/docs/administration/deployment/update-syteca.md)
>
> The checklist to follow before updating any deployment.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.