ZooKeeper Setup - GermainUX Docs

ServiceEnterprise

Availability2024.1

Configure ZooKeeper

Prepare ZooKeeper for GermainUX

Run ZooKeeper as a Windows service

Install as Windows service

Bootstrap the GermainUX configuration

Create required configuration paths

Troubleshooting

Fix ZooKeeper startup problems

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:

	Prerequisite
1	A compatible Java runtime is installed.
2	Port `2181`, or your configured client port, is available.
3	Germain Enterprise and the Germain nodes can reach the ZooKeeper host.
4	The ZooKeeper service account can access its installation and data directories.
5	The data directory has sufficient storage.
6	Firewalls permit communication between ZooKeeper and authorized GermainUX hosts.

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:

ZooKeeper installation directory
Java executable or Java home
zoo.cfg location
JVM memory settings
Log directory
Windows service name
Service account, when applicable

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:

The ZooKeeper hostname and port
The ZooKeeper path under which the settings will be stored
The path to the common.properties file

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:

	Step	Action
1	1	Start ZooKeeper.
2	2	Confirm that it accepts connections.
3	3	Start the other required infrastructure services.
4	4	Start Germain Enterprise.
5	5	Start the Germain nodes.
6	6	Verify that all GermainUX components connect without errors.

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:

Run ZooKeeper as an operating-system service.
Configure automatic startup and restart.
Use a three- or five-member ensemble when high availability is required.
Store ZooKeeper data on reliable, dedicated storage.
Monitor disk usage, JVM memory, latency, and ensemble health.
Restrict port 2181 to authorized systems.

Show all 10

Configure authentication and access-control lists where required.
Protect configuration values containing credentials or secrets.
Back up ZooKeeper configuration and data.
Keep all ensemble members on compatible ZooKeeper versions.

Do not expose ZooKeeper directly to the public internet.

Troubleshooting

ZooKeeper does not start

Check for:

Missing or incompatible Java runtime
Invalid zoo.cfg settings
An unavailable data directory
Incorrect directory permissions
A port conflict on 2181
Insufficient disk space
Incorrect Windows service paths or arguments

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

GermainUX cannot connect

Verify that:

ZooKeeper started before GermainUX.
The configured hostname resolves correctly.
The client port is listening.
Firewalls permit the connection.
GermainUX uses the correct environment root.
ZooKeeper is listening on an interface reachable from the GermainUX hosts.
Authentication settings match on both sides.

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.

Get Help

Contact GermainUX Support

The GermainUX team helps you get up and running faster, empower your team, turn data into actionable insights, and optimize performance to deliver measurable business outcomes.

Can't find what you need?

Search all GermainUX docs with Ctrl + K, or use the feedback buttons at the bottom of this page to tell us what is missing.

The content of this document is proprietary to GERMAIN SOFTWARE.

Configure ZooKeeper

Run ZooKeeper as a Windows service

Bootstrap the GermainUX configuration

Troubleshooting

​Supported version

​Prerequisites

​Install ZooKeeper

​Configure ZooKeeper

​1 Create the configuration file

​Configure the data directory

​Disable the ZooKeeper AdminServer

​Verify the client port

​Start ZooKeeper manually

​Linux

​Windows

​Run ZooKeeper as a Windows service

​1 Copy the service files

​Review the service configuration

​Install the service

​Start the service

​Bootstrap the GermainUX configuration

​1 Open the ZooKeeper CLI

​2 Create the required paths

​Import an existing common.properties file

​Startup order

​Validate the deployment

​Test the ZooKeeper connection

​Verify the GermainUX configuration

​Verify the listening port

​Production considerations

​Troubleshooting

​ZooKeeper does not start

​GermainUX cannot connect

​Bootstrap commands fail

​Get Help

Contact GermainUX Support

Can't find what you need?

Supported version

Prerequisites

Install ZooKeeper

Configure ZooKeeper

1 Create the configuration file

Configure the data directory

Disable the ZooKeeper AdminServer

Verify the client port

Start ZooKeeper manually

Linux

Windows

Run ZooKeeper as a Windows service

1 Copy the service files

Review the service configuration

Install the service

Start the service

Bootstrap the GermainUX configuration

1 Open the ZooKeeper CLI

2 Create the required paths

Import an existing `common.properties` file

Startup order

Validate the deployment

Test the ZooKeeper connection

Verify the GermainUX configuration

Verify the listening port

Production considerations

Troubleshooting

ZooKeeper does not start

GermainUX cannot connect

Bootstrap commands fail

Get Help