Compose for Multiple Docker Instances (Eval)

Docker Compose is a command-line tool used to define, run, and manage multi-container applications. NCache provides a Docker Compose configuration through Docker Hub that deploys multiple NCache Server containers and an Nginx load balancer on a single Linux VM. Docker Compose manages the deployment, while NCache Management Center is used to configure, manage, and monitor the caches.

Each NCache Server runs in a separate container on a private Docker network. The Nginx load balancer provides a common endpoint for client connections and NCache Management Center, eliminating the need to configure separate host port mappings or static IP addresses for individual NCache Server containers. You can also add or remove server containers using Docker Compose scaling commands.

Note

Docker Compose deployment is recommended only for evaluation.

Docker Compose Deployment

The Docker Compose deployment includes the following components:

Component Description
NCache Server containers Two NCache Server containers are deployed by default. The servers use private addresses within the Docker Compose network and form a cache cluster.
Nginx load balancer Provides a common endpoint for NCache clients on port 9800 and NCache Management Center on port 9801. It distributes initial client connections and uses session affinity for management requests.
Docker Compose network Enables communication among the NCache Server containers and the Nginx load balancer on the same Linux VM.

NCache provides a Docker Compose configuration on Docker Hub under the compose-5.3.8 tag. This configuration allows you to deploy multiple NCache Server containers without manually defining individual services or assigning container IP addresses. For the official NCache Docker resources, see the NCache-Docker GitHub repository.

Exposing Ports for Multiple NCache Instances

In a typical NCache deployment, each server exposes its ports for client communication and management. When multiple NCache Server containers run on the same Docker host, they use the same internal port numbers but have separate private addresses within the Docker network.

The Docker Compose deployment uses an Nginx load balancer to expose common host ports instead of requiring a separate host-port mapping for each NCache Server container. Nginx forwards initial NCache client connections on port 9800 and NCache Management Center requests on port 9801. It also forwards traffic for cache operations through ports 9831–9880, which NCache clients can use after the initial connection.

This configuration allows containers to be added or removed without manually assigning individual host ports or static IP addresses. For the key settings in the deployment file, see Compose File Attributes.

Prerequisites

Before deploying NCache using Docker Compose, ensure the following prerequisites are met:

  • Docker Engine and a compatible version of Docker Compose must be installed on the Linux VM.
  • A valid NCache evaluation key is available.

Configure Environment Variables

NCache uses environment variables to configure evaluation registration, the initial cache, and the NCache Server image version. Create a .env file in the directory from which you will run the Docker Compose commands, and provide the evaluation key. The other variables are optional.

KEY=your-evaluation-key
CACHE=defaultCache
SIZE=1024
TOPOLOGY=Partition-Replica
IMAGE_TAG=5.3.800

The following table describes the environment variables:

Note

Environment variables with asterisk (*) on their names are the required and the rest are optional.

Variable Default Value Description
KEY* None Specifies the NCache evaluation key used to register the server containers.
CACHE defaultCache Specifies the name of the cache created during deployment.
SIZE 1024 Specifies the cache size in MB per server.
TOPOLOGY Partition-Replica Specifies the topology of the cache created during deployment.
IMAGE_TAG 5.3.800 Specifies the NCache Server Docker image tag used for deployment. Set this to latest to use the latest available NCache image.
Important

The KEY environment variable is required for Docker Compose configuration. Ensure that the .env file is available in the working directory when running deployment, scaling, or shutdown commands. Removing the file or leaving KEY empty may prevent Docker Compose from processing the configuration.

Deploy NCache Using Docker Compose

To create a two-node NCache cluster, run the following command from the directory containing the .env file:

docker compose -f oci://docker.io/alachisoft/ncache:compose-5.3.8 up -d --wait --scale ncache=2

Docker Compose creates two NCache Server containers, an Nginx load balancer, and the required Docker network. The server containers use the supplied evaluation key, cache settings, and NCache Server image tag. If IMAGE_TAG is not specified, the deployment uses image tag 5.3.800. The -d option runs the containers in the background, while --wait waits until the services reach a running or healthy state.

The default Docker Compose project name is ncache-cluster. To assign a different project name, use the --project-name option with the deployment command.

Once the containers are running, access NCache Management Center in a browser using the Docker host's IP address:

http://<docker-host-ip>:9801

Nginx forwards the management requests to the NCache Server containers with session affinity. You can use NCache Management Center to view the servers and configure or manage caches in the deployment.

Note

NCache clients connect initially through the Docker host on port 9800. Connections for cache operations may also use the cache-host port range 9831–9880. Make sure these ports are accessible to clients connecting from outside the Docker Compose network.

Docker Compose Commands

Once the deployment has started, you can use Docker Compose commands to scale the NCache Server containers or stop the deployment.

Scale NCache Server Containers

To increase the number of NCache Server containers from two to three, run:

docker compose -f oci://docker.io/alachisoft/ncache:compose-5.3.8 up -d --wait --scale ncache=3 --no-recreate

The --no-recreate option prevents Docker Compose from recreating existing containers, even if their configuration has changed. This allows the deployment to add the new NCache Server container without recreating the existing ones.

To reduce the number of NCache Server containers from three to two, run:

docker compose -f oci://docker.io/alachisoft/ncache:compose-5.3.8 up -d --wait --scale ncache=2

Docker Compose adds or removes containers according to the specified scale. NCache's container startup and shutdown handling supports joining or leaving the configured cache cluster as nodes are added or removed. You can verify the updated cluster membership through NCache Management Center.

Stop the Docker Compose Deployment

To stop and remove the NCache Server containers, Nginx load balancer, and Compose network, run:

docker compose -f oci://docker.io/alachisoft/ncache:compose-5.3.8 down

The down command does not remove named volumes by default. For more information on Docker Compose commands, refer to the official Docker Compose CLI reference.

Compose File Attributes

The Docker Compose configuration defines the NCache Server service, the Nginx load balancer, their networking, and their startup behavior. The following table explains the key attributes used in the Compose file. For additional NCache Docker resources, see the official GitHub repository.

Attribute Description
name Defines the default Docker Compose project name, ncache-cluster. The project name is used to identify the resources created by the deployment.
services Defines the ncache and nginx services in the deployment.
image Specifies the Docker image used by each service. The NCache Server image tag can be configured using the IMAGE_TAG environment variable.
scale Specifies the default number of NCache Server containers. The --scale ncache=N command overrides this value.
ports Publishes Nginx endpoints on the Docker host. Individual NCache containers do not require separate published host ports.
environment Passes the evaluation key and cache settings to the NCache Server containers. The Compose configuration uses KEY, CACHE, SIZE, and TOPOLOGY to configure the server containers.
depends_on Specifies service startup dependencies, including the Nginx service's dependency on the NCache service.
configs Provides the Nginx configuration used to route client, cache-host, and management traffic.
healthcheck Uses the NCache-provided readiness scripts to check the container's state. Docker Compose uses the health-check result when evaluating container readiness with the --wait option.
restart Specifies the restart policy for the NCache and Nginx containers.
post_start Runs internal setup scripts after an NCache container starts. These scripts are part of the supplied deployment configuration and do not require customer customization.
stop_grace_period Allows the NCache container time to shut down when Docker Compose stops it.
volumes Defines the shared volume used by the NCache service for internal cluster coordination.
Note

The Compose file handles internal configuration and container startup. Customers configure the deployment through the supported environment variables and Docker Compose commands.

See Also

Getting Started with NCache Docker
Installation Types
Evaluation Period Management