Linux Docker
This guide explains how to run NCache Server in Docker using the official alachisoft/ncache image. It covers pulling the image, creating and starting containers (with recommended host networking), registering NCache with evaluation, and managing containers, enabling fast, scalable, and high-availability distributed caching for containerized environments.
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. Using these images, you can create containers that host NCache or create your own customized images by modifying the Dockerfiles.
Step 1 : Pull Image and Create Container
The easiest and quickest way to start using NCache is to fetch a pre-built NCache Docker Image from Docker Hub. These Docker images come preinstalled with NCache. Simply use “docker pull” command to install them in your environment. To get started with Docker in NCache, follow the steps mentioned below:
- Install Docker.
- Verify the correct installation by using the following:
docker version
If you are unable to get the version number, check Docker Troubleshooting section.
Pull the NCache Docker image from Docker Hub:
docker pull alachisoft/ncache:latest
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.
After pulling the Docker image, you need to create a Docker container. For a stable configuration and seamless integration, we strongly recommend utilizing the host network configuration for NCache deployments. This choice ensures that containers have direct access to the host's network interfaces and share the same IP and MAC address.
Note
The NCache Docker container is set up through host mode networking, i.e., from the network perspective, the applications inside the container are running on the host itself.
Run the following command using the host network mode:
docker create --name ncache --network host alachisoft/ncache:latest
Please note that ncache used in the command is the name of the container. You can choose any desired name for the container.
After creating the container, you need to start the Docker container.
docker start ncache
Step 2 : Register NCache
In order to use NCache, you first need to register your Docker container. You can choose between the following registration types:
- Cache Server (default)
- Dev/QA Server (only when registering for free evaluation)
You can either Register for Free Evaluation or activate NCache by selecting Activate with License Key depending on the registration type. In this guide we will be proceeding with the Cache Server registration.
Note
The default registration type for NCache is Cache Server, you can change this by updating the value of the registeras flag.
You can register using either of the following two options:
- Option 1: Register from inside the container shell.
- Option 2: Register from the host terminal, without entering the container.
In this guide we will be proceeding with the Option 2 i.e., Register from the host terminal for Free Evaluation using installation key.
Following are the steps to register with the CacheServer from the host terminal without entering the container:
- Run the full command from your host terminal without accessing the container shell:
docker exec -it ncache /opt/ncache/bin/tools/register-ncacheevaluation \
-key xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -registeras CacheServer
Note
Before creating a 2-node Partition-Replica cache, make sure you have two running and registered NCache server nodes.
Step 3: Create Distributed Cache
Once you are registered, you can create a 2-Node Partition-Replica cache through the NCache Management Center by following the steps mentioned below:
Launch the NCache Management Center at http://localhost:8251.
In the left navigation bar, go to Clustered Caches, and click on New.
In the resulting In-Memory Store page, select Distributed Cache as your store type and specify the name of your cache. Click Next.
Select the Partition-Replica caching topology and a Replication Strategy. Click Next.
Add two server nodes by specifying the Server Node IP/Name and click on the Add Node button for each. Click Next once all the required nodes are added.
Proceed with the preselected Cluster Port and Port Range, and accept any default settings, where required.
Enable auto-start cache as soon as it is created, or whenever the service starts. Click Finish to create 2-node cache cluster.
Note
To learn more about the options available to you as part of the cache creation process, please refer to the NCache Administrator's Guide.
Step 4 : Add Client
A client is your web or application server. This can be either a local or remote client. You can add it using the NCache Management Center. The process of adding client to your cache cluster is exactly the same for all store types. This section uses the example of the Distributed Cache store type.
On the Clustered Caches page, click on View Details against the appropriate Cache Name.
This opens up the detailed configuration page for the cache. In the Client Nodes tab, click Add and enter the Client Node IP/Name.
This connects your application server to the cache cluster.
Step 5: Test the Cluster
You can test the cluster using the NCache Management Center as follows:
- In the NCache Management Center, click "..." next to your cache and select the Show Statistics option.
- Set the Test-Stress timer to 1 minute. This is the duration for which data is added to your cache, and after this specific expiration time has elapsed, the data will be removed from the cache.
- Click on the Start button next to the timer to see live cache activity on the Server Dashboard.
Step 6: Monitor Cluster
Following a stress test, you must monitor your cluster to ensure performance stability. NCache provides a multi-layered monitoring strategy to track system resources and cache operations, using the NCache Management Center through Monitoring Dashboards and Tabular Statistics as follows:
In the NCache Management Center, click the "..." button against your cache name and select Monitor Cluster. Ensure the cache is already running.
NCache opens three real-time dashboards in a new tab:
Server Dashboard: Provides a graphical view of cluster health, event logs, and critical server-side counters like CPU Usage, Cache Size, and Requests/sec.
Client Dashboard: Displays client-side system resource usage and specific metrics such as Read/Write Operations/sec and Average Item Size.
Report Dashboard: Provides a consolidated view of cluster statistics in a detailed format.
To learn more about these dashboards, please see Monitor Using a Built-in NCache Monitor Dashboard section.
Note
For more details on using NCache, please refer to the Administrator's and Developer's Guides.
