Docker Deployment Overview
NCache provides Docker images for deploying NCache in Linux containers without installing it directly on the host operating system. Docker deployments support distributed cache servers, client-side services for containerized applications, and standalone development environments.
Important
NCache Docker images are only supported on Linux-based environments.
NCache supports the following container roles:
- Server: Hosts caches and participates in distributed cache clusters.
- Client: Provides client-side services, including OutProc Client Cache and client monitoring, for applications running in separate containers.
- Developer: Provides a standalone NCache environment for development and testing.
The selected role determines whether the container operates as an NCache Server, provides client-side services, or runs as a standalone Developer instance.
Note
NCache containers are automatically registered when they start using the evaluation or license information provided through environment variables. For details, refer to Docker Installation.
Choosing a Docker Deployment Model
| Deployment Model | Mode | Recommended For |
|---|---|---|
| Single Container per Host | Server | Production deployments requiring distributed caching. Each container runs as one cache server node. Typically deployed with one container per host. |
| Separate NCache Client and application containers | Client | OutProc Client Cache and client monitoring for containerized applications. |
| Standalone Developer container | Developer | Application development and testing with a standalone cache. |
| Multiple Containers per Host (Docker Compose) | Server | Evaluation and controlled testing of distributed caching on a single machine. Uses Docker Compose to deploy multiple NCache Server containers with an Nginx load balancer, shared client and management endpoints, and automatic cluster membership management during scaling. |
| Custom Docker Image | Server | Scenarios where the official NCache Docker image needs to be extended with additional dependencies, configuration, or scripts to meet specific requirements. |
NCache Server Container
NCache Server deployment runs NCache as a cache server node inside a Docker container. Each container runs an NCache Server instance and can be configured to join a distributed cache cluster. Containers registered as Server can host caches, join clusters, and communicate with other server nodes. Production deployments require appropriate Installation Types based on your environment and usage model.
NCache Server containers must be configured with the correct networking and ports to support cluster formation and inter-node communication. Required ports are documented in Firewalls and Ports. Host networking is recommended for NCache Server deployments, with one Server container per Linux VM. For networking details, refer to the Docker Installation Guide.
Cache Server Deployment Models
NCache Server containers can be deployed using different infrastructure models depending on how nodes are distributed across hosts.
Single Container per Host
In this model, each virtual machine or physical host runs one NCache Server container. When forming a distributed cluster, multiple machines each run their own container instance. This model mirrors traditional multi-server NCache deployments where each node runs on a separate machine. It is the recommended model for production deployments because if one machine goes down, the containers on other machines remain available, allowing the cache cluster to continue operating.
Multiple Containers per Host (Docker Compose)
Docker Compose enables multiple NCache Server containers to run on a single Linux VM for evaluation and testing. Each container operates as an independent cache server node within a private Docker network. The deployment also includes an Nginx load balancer that provides a common endpoint for NCache client connections on port 9800 and NCache Management Center on port 9801.
Docker Compose supports scaling the deployment by adding or removing NCache Server containers. When a container is added, it automatically registers and joins the configured caches. When a container is removed, it leaves the caches as part of the shutdown process. For deployment and scaling instructions, refer to Docker Compose.
Custom Image Deployment
A custom Docker image can be created by extending the official NCache Docker image. This allows you to include additional dependencies, configuration files, or scripts required for your environment. Regardless of image customization, containers must be registered with the appropriate role and configured with the required networking and ports for cluster communication. For details, refer to Customize Dockerfile.
Application and NCache Client Containers
Applications can run in Docker containers with the NCache Client SDK and connect to NCache Server containers. An InProc Client Cache runs within the application process. Applications requiring an OutProc Client Cache or client-side monitoring services can use a separate NCache Client container.
When the application and NCache Client run in separate containers, both containers must be connected to the same Docker bridge network. The application sets NCACHE_CLIENT_HOST to the NCache Client container name or IP address so that the SDK can locate the client-side services. The application must also be configured with the NCache Server connection information.
The NCache Client container is created using NC_REGISTER_AS=Client. Ports 9803 and 9804 must be published for its management and monitoring services, respectively. For the complete procedure, refer to Deploy the NCache Client Container with an Application.
Developer
Developer deployment is intended for development, testing, and other non-production environments. In this mode, the container runs as a standalone cache instance and does not participate in multi-node clustering. Containers registered as Developer are restricted to single-node operation and are subject to the following limitations:
- A maximum of 2 remote clients can connect to the local cache. Local client connections are unrestricted.
- A maximum of 3 caches can run with a combined cache size of 2 GB.
- Each local cache supports a maximum of 25 requests per second.
- A Developer-licensed client can send up to 200,000 requests to a remote cache during an application session. Once this limit is reached, a licensing exception is thrown. Restarting the application resets the request counter.
Note
NCache Developer is free to use.
Developer Deployment Model
Developer Docker deployments use a single container configuration. The container runs independently and does not require cluster setup or inter-node communication. This model is appropriate for testing application integration with NCache and developing caching logic locally. Since it operates as a standalone instance, the Developer deployment model is intended for development and testing rather than scalable production environments.
Docker Monitoring and Container Recovery
NCache supports container monitoring through NCache Monitor, Prometheus-compatible metrics, and OpenTelemetry integration. Container logs can also be viewed using standard Docker commands. The NCache metrics and service health endpoints are available on port 9804.
Docker restart policies can be configured for container recovery after the main container process exits. A restart policy does not, by itself, restart an otherwise running container when an application health endpoint reports an unhealthy state. Refer to Docker Installation for deployment instructions and the relevant monitoring documentation for configuration details.
In This Section
Docker Installation
Explains how to pull the NCache image, configure automatic registration, deploy Server, Client, and Developer containers, and manage the containers.
Docker Compose Explains how to deploy and scale multiple NCache Server containers on a single Linux VM using Docker Compose, with an Nginx load balancer providing shared client and management endpoints.
