Docker Installation

Docker enables you to deliver software quickly by separating your applications from your infrastructure. Thus, Docker acts as an “isolated, resource controlled, and portable operating environment” that can host any specific application on any machine without the hassle of deploying the environment manually. NCache provides Linux Docker images for Server, Client, and Developer deployments. Server containers can form distributed cache clusters across Linux VMs, while a separate NCache Client container supports OutProc Client Cache and client monitoring for containerized applications. This guide explains how to pull the NCache Docker image, create and register Docker containers, and manage them.

You can also customize NCache Docker images using the NCache Dockerfiles.

NCache provides Docker images hosted on the Docker Hub. Once the Docker environment has been set up, according to its prerequisites, you can pull the relevant images to start working on NCache.

How to Pull the NCache Docker Image from Docker Hub

Pull the pre-built NCache Docker image from Docker Hub by following these steps:

  • Install Docker.
  • Verify the Docker installation using the following command:
docker version

If you are unable to get the version number, refer to Troubleshooting the Docker daemon.

  • Pull the NCache Docker image from Docker Hub:
docker pull alachisoft/ncache:latest
Note

NCache Open Source (OSS) images are available on Docker Hub. To pull the image available for OSS, use a tag with the -oss suffix, for example: docker pull alachisoft/ncache:x.x.x-oss.

Important

When deploying in Production environment, it's recommended to use a specific NCache version tag (e.g., alachisoft/ncache:x.x.x) instead of latest. Since latest always pulls the most recent image, which may affect your existing setup.

Next, you need to create the NCache Docker container.

How to Create and Register the Docker Container

After pulling the Docker image, create an NCache Server container using Docker host networking. This allows the container to use the host's network interfaces directly without requiring explicit Docker port mappings.

For multi-VM NCache clusters, deploy a separate NCache Server container on each Linux VM. Ensure that the required NCache ports are accessible between VMs. Where network forwarding is required, forward TCP ports 9800–9999 as a range.

NCache supports automatic registration through environment variables specified when creating the Docker container. You can register NCache as Server, Client, or Developer using the NC_REGISTER_AS variable.

Register for Free Evaluation Using Installation Key

To register NCache for free evaluation, specify the installation key using the NC_KEY environment variable.

Run the following command to create the NCache Server container:

docker create --name ncache --network host -e NC_REGISTER_AS=Server -e NC_KEY="XXXXXXXXXXXXXX" alachisoft/ncache:latest

Activate Using Purchased License Key

To activate NCache using a purchased license, specify the license key and environment using NC_LICENSE_KEY and NC_LICENSE_ENV.

Run the following command to create the NCache Server container:

docker create --name ncache --network host -e NC_REGISTER_AS=Server -e NC_LICENSE_KEY="XXXXXXXXXXXXXX" -e NC_LICENSE_ENV=Production alachisoft/ncache:latest
Note

To activate your NCache license, you need to have the license key from Alachisoft Sales.

Note

NCache is automatically registered when the Docker container starts. You do not need to execute the registration commands manually.

After creating the container, you need to start the Docker container.

How to Start the Docker Container

Once the container is created, start it using the following command:

docker start ncache

When the container starts, NCache automatically completes the configured registration and starts the required services.

How to Deploy the NCache Client Container with an Application

NCache supports deploying the NCache Client and client application in separate Docker containers. The NCache Client container provides services for OutProc Client Cache and client monitoring.

Both containers must be connected to the same Docker bridge network. The client application uses the NCACHE_CLIENT_HOST environment variable to identify the NCache Client container.

Step 1: Create a Docker Network

Create a Docker bridge network using the following command:

docker network create ncache-client-net

You can also use an existing Docker bridge network.

Step 2: Run the NCache Client Container

Run the following command to create and start the NCache Client container:

docker run -d --name ncache-client --network ncache-client-net -p 9803:9803 -p 9804:9804 -e NC_REGISTER_AS=Client -e NC_KEY="XXXXXXXXXXXXXX" alachisoft/ncache:latest

Here, NC_REGISTER_AS=Client registers the container as an NCache Client. Ports 9803 (Cache Management RPC) and 9804 (metrics and service health) are published to the Docker host, as required for this deployment.

Step 3: Run the Application Container

Run the following command to deploy the client application on the same Docker network:

docker run -d --name ncache-client-app --network ncache-client-net -e NCACHE_CLIENT_HOST=ncache-client <application-image>:<tag>

Replace <application-image>:<tag> with the name and tag of your application image.

The NCACHE_CLIENT_HOST variable specifies the NCache Client container name or IP address, allowing the application to access the client-side NCache services.

Note

The NCache Client and application containers must be connected to the same Docker bridge network. The application must also be configured to connect to the NCache Server.

How to Deploy an NCache Developer Container

NCache supports deploying a Developer container for development and testing environments. The Developer container provides a standalone NCache installation with a maximum cache size of 2 GB and performance limitations.

To create and start an NCache Developer container using host networking, run the following command:

docker run -d --name ncache-dev --network host -e NC_REGISTER_AS=Developer -e NC_KEY="XXXXXXXXXXXXXX" alachisoft/ncache:latest

Here, NC_REGISTER_AS=Developer specifies the Developer role, while NC_KEY provides the installation key for registration.

Monitoring NCache Docker Containers

NCache supports monitoring Server and Client containers through NCache Monitor, Prometheus, and OpenTelemetry. Container logs can be viewed using Docker commands. OpenTelemetry export requires separate configuration.

To view the logs of an NCache container, run the following command:

docker logs ncache

NCache also provides health and metrics endpoints on port 9804 for monitoring the status of NCache services.

How to Stop the NCache Container

To stop a running NCache container, use the following command:

docker stop ncache

How to Remove the NCache Container

To remove an NCache container, first stop it using the command above.

Then, run the following command to remove the container:

docker rm ncache

Replace ncache with your container name, if different.

Note

Please ensure that you unregister NCache before removing the NCache container (licensed) to preserve and reuse the licenses.

How to Remove the NCache Docker Image

To remove the NCache Docker image from your Docker environment, use the following command:

docker rmi alachisoft/ncache:latest
Note

If you are using a different version or tag of the NCache image, replace latest with the specific tag you pulled (e.g., x.x.x).

NCache Docker References

NCache provides Dockerfiles and supporting resources on GitHub that include commands to build NCache images and offer flexibility for customization. You can use these Dockerfiles to make a customized image based on your dependencies to cater to specific needs.

NCache Docker Tags

The tag for NCache is as follows:

alachisoft/ncache:latest

NCache Dockerfiles

You can customize the NCache Dockerfiles to build images tailored to your specific dependencies and requirements. To do this effectively, it's important to understand what the provided Dockerfiles include and how they are structured, as discussed below.

What does NCache Dockerfile contain?

The Dockerfiles provided by NCache at GitHub contain commands to build images for NCache. Before you proceed any further, you need to clone this repo to your local machine and download the NCache setup and place it under the resources folder. Note that to create the image using this Dockerfile, the following resources are required:

  • Dockerfile: This file defines the steps to build the NCache image, including setting up the base OS, installing dependencies, copying resources, and running the installation, and startup scripts. Dockerfiles can be customized to perform additional tasks.

  • NCache setup file: This is a .tar.gz file that can be downloaded from Alachisoft.com.

  • installncache.sh: The installncache.sh script extracts the NCache tar.gz and installs NCache at the installation path /opt.

  • ipbinding.sh: The ipbinding.sh script extracts the IP address of the container on the very first usage of container and updates that IP in the NCache configuration files accordingly.

  • startup.sh: The startup script runs on container startup. It calls ipbinding.sh which replaces the IP with the actual IP assigned to the container on the first time the container is started. Furthermore, the startup.sh script starts ncached, along with the ncacheloaderd and ncachebridged daemon services.

These resources must be placed in the following file structure (as also arranged on GitHub):

/resources
    ├── installncache.sh
    ├── ipbinding.sh
    ├── startup.sh
    └── ncache.ent.net.tar.gz
Dockerfile

NCache Dockerfile Build and Runtime Behavior

This section outlines how the NCache Docker image is built and how the container initializes NCache services at runtime using the NCache Dockerfiles:

Dockerfile Build-time Actions

The NCache Dockerfile defines the steps to build the Docker image. Key build-time actions include:

  • Base Image: Uses ubuntu:22.04 as the base operating system image.

  • Working Directory: Sets /app as the working directory inside the container.

  • Copy Resources: Copies the resources folder (including setup files and scripts) into the container.

  • Expose Ports: Exposes TCP ports 9800–9999 for NCache services, cache communication, management, and monitoring.

  • Install Prerequisites: Updates package lists and installs required packages such as procps, ed, curl, and libicu-dev.

  • Install NCache: Runs the installncache.sh script to extract and install NCache Linux setup. Installation parameters like user name, company, and email are passed here.

  • User Setup: Switches the current user to ncache for security and permission purposes.

  • Set Entrypoint: Defines the container’s runtime entrypoint as /app/startup.sh.

Container Startup and Runtime Behavior

The NCache Dockerfile defines /app/startup.sh as the container entrypoint. When the container starts, the script performs the following operations:

  • IP Binding: Executes ipbinding.sh to configure the container's IP address in the NCache configuration files.

  • NCache Registration: Executes activate.sh to register NCache using the evaluation or license information provided through environment variables.

  • Starting NCache Services: Starts the NCache Service and the required supporting services, including the Bridge and Execution services.

These operations are performed automatically when the Docker container starts.

Customize Dockerfile

You can customize the NCache Dockerfile as per your requirement to perform any additional tasks after or before installation. You can then create your customized images using this Dockerfile and push them to Docker Hub or your local repository. All of this is explained below.

How to Create Images using Customized Dockerfile

Once you've made your changes to the Dockerfile, follow these steps to create the Docker image:

  1. Navigate to the relative path where the Dockerfile is located.

  2. Run the command to build a Docker image from the customized Dockerfile.

    docker build . -t myrepo/ncache:v1

    The tag myrepo/ncache:v1 is a user-defined name and version for the image.

  3. To verify that the image has been created, run the command docker images that lists all images and their details.

How to Push Image

Once your customized Docker Image(s) have been created, you can push it to a public or local repository using the docker push command. The following command pushes the image ncache with the tag v1 to Docker Hub public repository:

docker push myrepo/ncache:v1

See Also

Installation Types
Evaluation Period Management