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 NCache Enterprise and Professional 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 start the NCache Docker container.

Start the Docker Container

After pulling the Docker image, you must start a Docker container on the relevant box. 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 start the Docker container:

docker run --name ncache -itd --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.

If you want to auto-activate NCache container (by using either Installation or Purchased License Key) using the docker run command, please refer to the Auto-Activate NCache Containers section.

After starting the container, the next step is to connect to the running container instance.

Connect to the Docker Container

Once the NCache containers are created and running, you can access these containers by using docker exec command and specifying the container name of the newly created container.

The following command connects you to the container ncache using the docker exec command:

docker exec -it ncache bash

After connecting to 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
  • Dev/QA Server (only when registering for free evaluation)
  • Remote Client

You can either register for free evaluation or activate NCache by selecting Activate with License Key depending on the registration type, as explained below.

Note

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

Important
  • The tools specified below for registration are located in /opt/ncache/bin/tools, commonly referenced via the $NCHOME variable (typically set to /opt/ncache).
  • If $NCHOME isn’t set, you can define it manually: export NCHOME=/opt/ncache.
  • If this folder isn't in your $PATH, either use the full path to run the tool or add it to your path like this: export PATH=$PATH:$NCHOME/bin/tools.

Register Cache Server

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

  • Using Installation Key:
register-ncacheevaluation -key xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -firstname John -lastname Smith -email john@yourdomain.com -registeras CacheServer -company your_company_name
  • Using the Purchased License Key:
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:
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.

Register Remote Client

To register as a Remote Client, you need to specify the installation type RemoteClient using the registeras flag.

  • Using Installation Key:
register-ncacheevaluation -key xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -firstname John -lastname Smith -email john@yourdomain.com -registeras RemoteClient -company your_company_name
  • Using the Purchased License Key:
register-ncache -key xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -environment Production -firstname John -lastname Smith -email john@yourdomain.com -registeras RemoteClient -company your_company_name

Auto-Activate NCache Containers (NCache 5.3 SP5 and Above)

Starting with NCache 5.3 SP5, NCache supports automatic activation at container startup through the use of environment variables passed via the docker run command. This allows you to bypass manual activation steps after container creation.

You need to provide the same registration details (name, email, company, and either an Installation Key or a Purchased License Key) through NCache-specific environment variables, and NCache handles the activation process as the container starts. These environment variables are passed using the --env flag in Docker. You can learn more about how Docker handles environment variables in the Docker CLI documentation.

Below are the sample docker run commands demonstrating how to activate NCache using either an Installation Key or a Purchased License Key via environment variables:

Note

The default registration type for NCache is Cache Server, you can change this by updating the value of the NC_REGISTER_AS environment variable. It supports three possible values, CacheServer (default), Developer (only when registering using Installation Key), and Remote Client.

Important

If both NC_INSTALL_KEY and NC_LICENSE_KEY are provided in the command, NC_LICENSE_KEY takes precedence.

Register Cache Server

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

  • Using Installation Key:
docker run --name ncache --env NC_FIRST_NAME=John --env NC_LAST_NAME=Smith --env NC_EMAIL=john@yourdomain.com --env NC_COMPANY=your_company_name --env NC_INSTALL_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx --env NC_REGISTER_AS=CacheServer -itd alachisoft/ncache:latest
  • Using the Purchased License Key:
docker run --name ncache --env NC_FIRST_NAME=John --env NC_LAST_NAME=Smith --env NC_EMAIL=john@yourdomain.com --env NC_COMPANY=your_company_name --env NC_LICENSE_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx --env NC_ENVIRONMENT=Production --env NC_REGISTER_AS=CacheServer -itd alachisoft/ncache:latest

Register Dev/QA Server

To register as a Dev/QA Server, you need to specify the installation type Developer using the NC_REGISTER_AS environment variable.

  • Using Installation Key:
docker run --name ncache --env NC_FIRST_NAME=John --env NC_LAST_NAME=Smith --env NC_EMAIL=john@yourdomain.com --env NC_COMPANY=your_company_name --env NC_INSTALL_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx --env NC_REGISTER_AS=Developer -itd alachisoft/ncache:latest
Note

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

Register Remote Client

To register as a Remote Client, you need to specify the installation type RemoteClient using the NC_REGISTER_AS environment variable.

  • Using Installation Key:
docker run --name ncache --env NC_FIRST_NAME=John --env NC_LAST_NAME=Smith --env NC_EMAIL=john@yourdomain.com --env NC_COMPANY=your_company_name --env NC_INSTALL_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx --env NC_REGISTER_AS=RemoteClient -itd alachisoft/ncache:latest
  • Using the Purchased License Key:
docker run --name ncache --env NC_FIRST_NAME=John --env NC_LAST_NAME=Smith --env NC_EMAIL=john@yourdomain.com --env NC_COMPANY=your_company_name --env NC_LICENSE_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx --env NC_ENVIRONMENT=Production --env NC_REGISTER_AS=RemoteClient -itd alachisoft/ncache:latest

Using an .env File for NCache Activation

Instead of passing each environment variable individually using multiple --env flags, you can simplify the process by using the --env-file option. This allows Docker to load all required environment variables from a single file—making your container setup cleaner and easier to manage. You can learn more about this flag from here.

Following is the sample ncache.env file for registering NCache using the Installation Key:

# User information required for activation/evaluation
NC_FIRST_NAME=John
NC_LAST_NAME=Smith
NC_EMAIL=john@yourdomain.com
NC_COMPANY=your_company_name

# Register the container as CacheServer | RemoteClient | Developer 
NC_REGISTER_AS=CacheServer

# Provide the NCache Installation key to use the NCache in the evaluation mode
NC_INSTALL_KEY='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

This is how you can use a .env file to activate an NCache container:

docker run --name ncache --env-file ncache.env -itd alachisoft/ncache:latest

However, for registration using the Purchased License Key, ncache.env should contain NC_LICENSE_KEY and NC_ENVIRONMENT variables, instead of NC_INSTALL_KEY.

Once NCache is auto-activated at container startup, the container is ready for use. You can now begin creating caches, adding nodes, or managing the cluster using the NCache Management Center.

Run Multiple Containers Using Docker Compose

Docker Compose is a command-line tool used to define, manage, and run multi-container applications using a YAML configuration file. The primary file used, compose.yaml, lets you describe your services, networks, volumes, and how containers should behave. Refer to Docker Documentation to see how this command works.

You can deploy a complete NCache cluster using Docker Compose by describing multiple NCache containers in the YAML file and running them together. For details on how Docker Compose works and its application model, refer to the official Docker guide. It offers multiple ways to configure and run containers, including registration through lifecycle commands or environment variables.

Example: Compose File

Below is a sample compose.yaml file defining three NCache containers, each using three different methods to register itself after startup:

# NCache Cluster Definition
name: myproject

services:
 ncache1:
    image: alachisoft/ncache:latest
    container_name: ncache1
    hostname: ncache1
    ports:
      - "8251:8251"             # Managment UI (http)
      - "9801:9800"             # Client Connection
      - "1800-1810:8300-8310"   # Cache Host Ports
    networks:
      ncache-net:
        ipv4_address: 172.28.0.11
    environment:
      NC_FIRST_NAME: "John"
      NC_LAST_NAME: "Smith"
      NC_EMAIL: "john@yourdomain.com"
      NC_COMPANY: "your_company_name"
      NC_INSTALL_KEY: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

  ncache2:
    image: alachisoft/ncache:latest
    container_name: ncache2
    hostname: ncache2
    ports:
      - "8252:8251"             # Managment UI (http)
      - "9802:9800"             # Client Connection
      - "2800-2810:8300-8310"   # Cache Host Ports
    networks:
      ncache-net:
        ipv4_address: 172.28.0.12
    env_file: "ncache.env"

  ncache3:
    image: alachisoft/ncache:latest
    container_name: ncache3
    hostname: ncache3
    ports:
      - "8253:8251"             # Managment UI (http)
      - "9803:9800"             # Client Connection
      - "3800-3810:8300-8310"   # Cache Host Ports
    networks:
      ncache-net:
        ipv4_address: 172.28.0.13
    depends_on:
      - ncache1
      - ncache2
    post_start:
      - command: "/opt/ncache/bin/tools/register-ncacheevaluation -firstname John -lastname Smith -email john@yourdomain.com -company your_company_name -key'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' "

networks:
  ncache-net:
    driver: bridge
    ipam:
      config:
        - subnet: 172.28.0.0/24

Next, use the following command to start all services defined in your compose.yaml file:

docker compose up

Furthermore, use the following command to stop the running NCache containers using docker compose:

docker compose down

This command stops and removes all containers, networks, and volumes created by docker compose up.

You can also view logs with:

docker compose logs

For further details, please refer to the official Docker guide.

The following sections explain each of the three registration methods demonstrated in the above compose.yaml file.

Using post_start Lifecycle Hook

You can use the post_start hook in Docker Compose to run a command after the container starts. The post_start lifecycle hook allows you to define custom commands that should run after the container starts. This is useful for running setup operations, such as activating NCache containers using the registration tool right after the container is up. This method gives you flexibility and works consistently across all NCache versions. For more details, see the official Docker guide on post_start hooks.

Important

The post_start lifecycle hook is supported in Docker Compose version 2.30.0 and above. Ensure you are using this version or later to use post_start commands in your Compose files.

Passing Environment Variables for Configuration

NCache also supports container registration through environment variables. These can be configured in your compose.yaml file using either the environment or env_file attributes, as discussed below.

Note

Environment variable-based registration is only supported in NCache version 5.3 SP5 and above.

  • Using the environment attribute: This method defines environment variables directly inside the compose.yaml file, within the service configuration.

  • Using the env_file attribute This method references a separate ncache.env file to load environment variables, keeping the compose.yaml file cleaner and easier to manage.

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.

Restart the NCache Container

You can restart your NCache container later using the following command:

docker start ncache

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

The Dockerfiles provided by NCache at GitHub contain commands to build images for NCache. NCache also provides Dockerfiles and supporting resources on GitHub to allow for more flexibility while using the NCache Docker images. You can use these Dockerfiles to make a customized image based on your dependencies to cater to specific needs.

NCache Docker Tag

NCache offers both Enterprise and Professional edition tags. For instance, for NCache Enterprise, the tag is as follows:

alachisoft/ncache:latest

NCache Dockerfiles

You can use the NCache Dockerfiles to make a customized image with your customized dependencies to cater to your specific needs. You can make these changes within the respective Dockerfiles and build your customized images.

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 resource folder. Note that to create the image using this Dockerfile, the following resources are required:

  • Dockerfile: Dockerfiles can be customized to perform additional tasks.

  • NCache Enterprise/Professional 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 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.

  • activate.sh: This script automates the activation of NCache by setting the required environment variables.

These resources must be placed in the following file structure (as also arranged on GitHub). Make sure that the resources folder exists in the same directory as the Dockerfile.

  1. Dockerfile
  2. ipbinding.sh, startup.sh, activate.sh, installncache.sh, and ncache setup file in the resources folder.

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