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 Docker images hosted on the Docker Hub. Once the Docker environment has been set, 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.

Pull the NCache Docker Image from Docker Hub

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:5.3.5) 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.

Create the 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's perspective, the applications inside the container are running on the host itself.

Unlike the bridge network, which provides isolation between containers connected to the same network, the host network eliminates the need for explicit port mapping. Hence, bridge network is not recommended for NCache deployments. This allows developers to create an NCache container on their workstations for developing, debugging, and testing client applications.

Run the following command using the host network to create the Docker container:

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.

Start the Docker Container

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

docker start ncache

After starting the container, the next step is to register NCache.

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.

Note

The default registration type for NCache is Cache Server, you can change this by updating the value of the registeras flag.

Note

You cannot register as a Remote Client using NCache Docker.

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.

Register Cache Server

You may specify the installation type CacheServer using the registeras flag, although it is not required. If the registeras flag is omitted, the container is registered as a Cache Server by default.

• Using Installation Key:

  • Option 1 (Register from inside the container)

    First, run the following command to access the container shell:

    docker exec -it ncache bash
    

    Then execute the registration command inside the container:

    /opt/ncache/bin/tools/register-ncacheevaluation -key xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -firstname John -lastname Smith -email john@yourdomain.com -registeras CacheServer -company your_company_name
    

  • Option 2 (Register from the host terminal)

    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 -firstname John -lastname Smith -email john@yourdomain.com -registeras CacheServer -company your_company_name
    

• Using the Purchased License Key:

  • Option 1 (Register from inside the container)

    First, run the following command to access the container shell:

    docker exec -it ncache bash
    

    Then execute the registration command inside the container:

    /opt/ncache/bin/tools/register-ncache -key xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -environment Production -firstname John -lastname Smith -email john@yourdomain.com -registeras CacheServer -company your_company_name
    

  • Option 2 (Register from the host terminal)

    Run the full command from your host terminal without accessing the container shell:

    docker exec -it ncache /opt/ncache/bin/tools/register-ncache -key xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -environment Production -firstname John -lastname Smith -email john@yourdomain.com -registeras CacheServer -company your_company_name
    

Note

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

Register Dev/QA Server

To register as a Dev/QA Server, you need to specify the installation type Developer using the registeras flag.

• Using Installation Key:

  • Option 1 (Register from inside the container)

    First, run the following command to access the container shell:

    docker exec -it ncache bash
    

    Then execute the registration command inside the container:

    /opt/ncache/bin/tools/register-ncacheevaluation -key xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -firstname John -lastname Smith -email john@yourdomain.com -registeras Developer -company your_company_name
    

  • Option 2 (Register from the host terminal)

    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 -firstname John -lastname Smith -email john@yourdomain.com -registeras Developer -company your_company_name
    

Note

You cannot register as a Dev/QA Server using a Purchased License Key.

Stop the NCache Container

If your NCache container is currently running and you want to stop it, use the following command:

docker stop ncache

Replace ncache with your container name, if different.

Remove the NCache Container

To remove the NCache container from your Docker environment, you must stop the container first. Use the following command to remove the NCache container:

docker rm ncache

Replace ncache with your container name, if different.

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., 5.3.5).

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

NCache offers both Enterprise and Community edition tags. For instance, for NCache Enterprise, the tag 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, and for the Enterprise edition, it also starts 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: Opens necessary ports (8250-8260, 9800, 8300-8400) used by NCache for communication and clustering.

• 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 Dockerfile specifies an ENTRYPOINT that runs the startup.sh script on container start. This script performs the following steps:

• IP Binding for NCache Configuration: This script checks for and executes ipbinding.sh, which retrieves the container's current IP address and updates NCache’s configuration files accordingly. This step ensures proper cluster communication.

• Starting the NCache Daemon: After the IP binding, the script starts the NCache service by launching the Alachisoft.NCache.Daemon process (ncached). For the Enterprise edition, it also starts the ncacheloaderd and ncachebridged daemon services. This initializes NCache inside the container, making it ready for caching operations.

This startup sequence runs automatically every time the container is launched, ensuring a consistent and ready-to-use environment for NCache regardless of where the container is deployed.

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.

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 following command to build the image:

   docker build . –t myrepo/ncache:v1
   

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

Important

Similarly, if you want to use the OutProc cache on the client container or you want to monitor NCache Client Counters, you can build the NCache Client image using the same process.

Push Image

Once your customized Docker Image(s) have been created, you can push it to a public or local registry 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

License Management
Licensing Model
Evaluation Period Management