ZooKeeper Setup

⚙️ Apache ZooKeeper Setup

Apache ZooKeeper is a centralized coordination service used by GermainUX to store configuration, synchronize distributed components, manage naming, and coordinate services.

🔖 Supported version

GermainUX supports Apache ZooKeeper 3.6.3 or later.

Use the ZooKeeper version approved for your GermainUX release. Download it from the Apache ZooKeeper website.

📋 Prerequisites

Before installing ZooKeeper, confirm that:

The instructions below configure a single ZooKeeper instance. For production environments requiring high availability, deploy a ZooKeeper ensemble according to your organization’s infrastructure standards.

📦 Install ZooKeeper

Extract the ZooKeeper archive to the desired directory.

Example installation locations:

Linux:   /opt/zookeeper
Windows: C:\opt\zookeeper

The remaining examples assume these paths.

🔧 Configure ZooKeeper

1️⃣ Create the configuration file

ZooKeeper includes a sample configuration. Copy it to zoo.cfg:

cp /opt/zookeeper/conf/zoo_sample.cfg /opt/zookeeper/conf/zoo.cfg

On Windows, copy:

C:\opt\zookeeper\conf\zoo_sample.cfg

to:

C:\opt\zookeeper\conf\zoo.cfg

📁 Configure the data directory

Open zoo.cfg and set:

dataDir=/opt/zookeeper/data

On Windows, use an appropriate Windows path:

dataDir=C:/opt/zookeeper/data

Create the directory if it does not already exist:

mkdir -p /opt/zookeeper/data

Ensure that the account running ZooKeeper can read and write to this directory.

⛔ Disable the ZooKeeper AdminServer

Add the following entries to zoo.cfg:

admin.enableServer=false
admin.serverPort=9080

Disabling the AdminServer prevents its embedded HTTP interface from starting. The port setting has no effect while the AdminServer is disabled, but may be retained for consistency with the GermainUX configuration template.

📞 Verify the client port

The standard ZooKeeper client port is:

clientPort=2181

If you change it, update the corresponding GermainUX connection configuration and firewall rules.

🚀 Start ZooKeeper manually

Manual startup is suitable for development, testing, and initial validation. Run ZooKeeper as an operating-system service in production.

🐧 Linux

Start ZooKeeper:

/opt/zookeeper/bin/zkServer.sh start

Check its status:

/opt/zookeeper/bin/zkServer.sh status

Stop ZooKeeper:

/opt/zookeeper/bin/zkServer.sh stop

💻 Windows

Open Command Prompt and run:

C:\opt\zookeeper\bin\zkServer.cmd

Keep the command window open while ZooKeeper is running.

🚪 Run ZooKeeper as a Windows service

GermainUX provides the files required to install ZooKeeper as a Windows service.

1️⃣ Copy the service files

Copy the following files from:

{serviceDistroDirectory}\install\zookeeper\

to the ZooKeeper bin directory:

ZooKeeperService.exe
ZooKeeperService.xml

🔍 Review the service configuration

Before installing the service, verify the following settings in ZooKeeperService.xml:

🛠️ Install the service

Open Command Prompt as an administrator, navigate to the ZooKeeper bin directory, and run:

ZooKeeperService.exe install

▶️ Start the service

Start the Apache ZooKeeper Windows service using the Windows Services console or your organization’s service-management process.

Configure the startup type as Automatic when ZooKeeper must start with Windows.

🌱 Bootstrap the GermainUX configuration

After starting ZooKeeper, create the configuration paths required by GermainUX.

1️⃣ Open the ZooKeeper CLI

On Linux:

/opt/zookeeper/bin/zkCli.sh

On Windows:

C:\opt\zookeeper\bin\zkCli.cmd

If ZooKeeper runs on another host, specify its address:

/opt/zookeeper/bin/zkCli.sh -server <zookeeper-host>:2181

2️⃣ Create the required paths

Run the following commands inside the ZooKeeper CLI:

create /config ""
create /config/germain ""
create /config/germain/rest-services ""
create /config/germain/rest-services/logging.config "${catalina.base}/conf/rest-logback.xml"
create /config/germain/ingestion-services ""
create /config/germain/ingestion-services/logging.config "${catalina.base}/conf/ingestion-logback.xml"

In this example, germain is the environment name.

Change it only when multiple GermainUX environments share the same ZooKeeper cluster. For example:

/config/prod
/config/stage

Each GermainUX environment must be configured to use its corresponding configuration root.

📥 Import an existing common.properties file

Existing settings can be imported using the GermainUX ZkConfig utility from:

germain-apm\Util\ZkConfig

The utility requires:

Example:

java com.germainsoftware.apm.zkconfig.ZKConfig \
  127.0.0.1:2181 \
  /config/germain/application \
  common.properties

Alternatively, execute the commands provided in:

{serviceDistroDirectory}\install\zookeeper\bootstrap.zk

Review the properties before importing them. The file may contain environment-specific URLs, credentials, or other sensitive configuration.

▶️ Startup order

Use the following startup sequence:

✅ Validate the deployment

🔎 Test the ZooKeeper connection

Open the ZooKeeper CLI:

/opt/zookeeper/bin/zkCli.sh -server localhost:2181

A successful connection displays a ZooKeeper command prompt.

📁 Verify the GermainUX configuration

From the ZooKeeper CLI, run:

ls /config
ls /config/germain
ls /config/germain/rest-services
ls /config/germain/ingestion-services

Confirm that the expected paths and values are present:

get /config/germain/rest-services/logging.config
get /config/germain/ingestion-services/logging.config

📡 Verify the listening port

On Linux:

ss -ltn | grep 2181

From a GermainUX host:

nc -vz <zookeeper-host> 2181

🏭 Production considerations

For production deployments:

Do not expose ZooKeeper directly to the public internet.

Troubleshooting

🔁 ZooKeeper does not start

Check for:

Review the ZooKeeper log and console output for the original startup error.

🔗 GermainUX cannot connect

Verify that:

🔧 Bootstrap commands fail

If a command reports that a node already exists, inspect its value before changing or deleting it:

get <path>

Do not overwrite or remove an existing production configuration until you have confirmed which GermainUX environment uses it and backed up its current value.

Source: ZooKeeper Setup.