KB-1926 How to remove servers from a distributed installation for self-managed


This article describes how to remove servers from an self-managed distributed installation of Appian. The documentation here applies only for self-managed customers running on Linux servers - a distributed installation of Appian on Windows servers is not supported. Customers who are on Appian Cloud should not follow these instructions and instead create a case with Appian Technical Support detailing their request. 

The below steps will cause Appian to be unavailable until all steps are completed. Please schedule a maintenance window and inform your users. 

Note: When moving from High Availability to Standalone, it is recommended to adjust autocheckpoint configuration so that checkpoints do not run during business hours. More information is provided in the Configuring Checkpointing Frequency documentation.


The links redirect to documentation corresponding to the latest version of Appian. Be sure to select the documentation version that corresponds to the version of Appian you have installed. 

Stop a Subset of Appian Services 

  1. Determine if any of the servers you are removing are hosting Kafka & Zookeeper.
    If not, complete all steps in Stopping the Application Suite on Linux, then proceed to the 'Change Topology' section and skip all instructions in between.

    Otherwise, complete all steps prior to the one that says to “Stop the Appian engines” in  Stopping the Application Suite on Linux and follow all directions in the rest of this article.

  2. Stop Service Manager & Engines without stopping Zookeeper & Kafka on all engine nodes by running: 
    <APPIAN_HOME>/services/bin/stop.sh -p <password> -no-kafka -s all

Move Kafka Data to Remaining Servers 

  1. If the server(s) you are removing are running Kafka, note their hostnames and Kafka ports of those server(s).
    1. A list of Kafka host and ports can be found in under the <kafka-cluster> element in the below file path. Please see the below path depending on the version of Appian installed:
      1. 19.1 and later: <APPIAN_HOME>/conf/appian-topology.xml 
      2. Pre-19.1: <APPIAN_HOME>/ear/suite.ear/conf/appian-topology.xml
    2. The first Kafka broker listed in the topology is recognized as the primary broker and cannot be excluded from the cluster. If the node you would like to keep is not the first Kafka broker listed in the topology, update the topology file to make it the first broker in the cluster and restart IMS components in the environment.
    3. Kafka brokers should be removed in the reverse order in which they are listed in the topology file. 

  2. Remove partitions from the brokers that will be removed by running the following on one of the Kafka nodes: 
    <APPIAN_HOME>/services/lib/scripts/decreaseBrokerCount.sh --exclude-brokers host:port
    1. Run the script to exclude unneeded brokers one at a time. Replace host:port with <kafka-hostname> and Kafka port (the default port is 9092)

  3. Make sure that the brokers in step 2 are no longer replicating any partitions by running the following using any Kafka host and port:
    <APPIAN_HOME>/services/kafka_<versionInfo>/bin/kafka-topics.sh --describe --bootstrap-server <kafka-hostname>:9092
    1. <kafka-hostname>:9092 is the hostname or IP address where any of the Kafka servers is running. If Kafka is not running with the default client port (9092), include the port as well: hostname:1234
    2. Make sure that the broker-id of the brokers that will be removed do NOT appear in the values for any column. The highest broker-id displayed = (your target Kafka cluster size) - 1.  

Stop Remaining Appian Services

  1. Stop Kafka cluster on all engine nodes.
    <APPIAN_HOME>/services/stop.sh -p <password> -s kafka

  2. Once all Kafka brokers have stopped, stop Zookeeper on all engine nodes by running: 
    <APPIAN_HOME>/services/stop.sh -p <password> -s zookeeper

Change Topology

  1. Edit <APPIAN_HOME>/conf/appian-topology.xml (after 19.1) or <APPIAN_HOME>/ear/suite.ear/conf/appian-topology.xml (before 19.1) on every server that will remain. The topology file must be the same on all servers.

    The topology file should reflect the end state of where each Appian Service will be running. 
    <?xml version="1.0" encoding="UTF-8"?>
    <topology port="5000">
    <server host="<hostname>">
    <engine name="forums"/>
    <engine name="notify"/>
    <engine name="notify-email"/>
    <engine name="channels"/>
    <engine name="content"/>
    <engine name="collaboration-statistics"/>
    <engine name="personalization"/>
    <engine name="portal"/>
    <engine name="process-design"/>
    <engine name="process-analytics0"/>
    <engine name="process-analytics1"/>
    <engine name="process-analytics2"/>
    <engine name="process-execution0"/>
    <engine name="process-execution1"/>
    <engine name="process-execution2"/>
    <search-server host="<hostname>" port="9300"/>
    <broker host="<hostname>" port="9092"/>
    <zookeeper host="<hostname>" port="2181"/>
    <data-server host="<hostname>" port="5400" rts-count="2"/>
  2. Deactivate the unnecessary server(s).
    This step is handled by the customer’s System Administrator.

Restart Appian

  1. Make sure you are looking at the version of the documentation that matches the version of Appian you are running.  
    Follow all steps in Starting the Application Suite on Linux.

Affected Versions

This article applies to Appian 18.2 and later.

Last Reviewed: Feb 2023