Deploying a {{page.netscaler-cpx-short}} Instance in Docker

Last published : Sep 02, 2026
{{page.netscaler-cpx-short}} instances are available as a Docker image file in the Quay container registry. To deploy an instance, download the {{page.netscaler-cpx-short}} image from the Quay container registry and then deploy the instance by using the docker run command or the Docker compose tool.

Prerequisites

Make sure that:
  • Docker host system has at least:
    • 1 CPU
    • 2 GB RAM
      Note: For better {{page.netscaler-cpx-short}} performance, you can define the number of processing engines that you want the {{page.netscaler-cpx-short}} instance to start. For every additional processing engine, you add, make sure that the Docker host contains the equivalent number of vCPUs and amount of memory in GB. For example, if you want to add 4 processing engines, the Docker host must contain 4 vCPUs and 4 GB of memory.
  • Docker host system is running Linux Ubuntu version 14.04 or later.
  • Docker version 1.12 is installed on the host system. For information about Docker installation on Linux, see the Docker Documentation.
  • Docker host has Internet connectivity.
    Note: {{page.netscaler-cpx-short}} has issues while running on ubuntu version 16.04.5, kernel version 4.4.0-131-generic. So, it is not recommended to run {{page.netscaler-cpx-short}} on ubuntu version 16.04.5 kernel version 4.4.0-131-generic.

Downloading {{page.netscaler-cpx-short}} Image from Quay

You can download {{page.netscaler-cpx-short}} image from the Quay container registry using the docker pull command and deploy it on your environment. Use the following command to download the {{page.netscaler-cpx-short}} image from the Quay container registry:
docker pull quay.io/citrix/citrix-k8s-cpx-ingress:tag
In this command, tag specifies the Citrix the {{page.netscaler-cpx-short}} image.
For example, if you want to download the version 12.1-51.16, then use the following command:
docker pull quay.io/citrix/citrix-k8s-cpx-ingress:12.1-51.16
Use the following command to verify if {{page.netscaler-cpx-short}} image is installed in docker images:
root@ubuntu:~# docker images | grep 'citrix-k8s-cpx-ingress'
quay.io/citrix/citrix-k8s-cpx-ingress                  12.1-51.16          952a04e73101        2 months ago        469 MB
Note: It is recommended to use the latest {{page.netscaler-cpx-short}} image from the Quay container registry for availing the latest features of {{page.netscaler-cpx-short}}.

Deploying the {{page.netscaler-cpx-short}} Instance Using the docker run Command

On the host, you can install a {{page.netscaler-cpx-short}} instance in the Docker container by using the {{page.netscaler-cpx-short}} Docker image that you loaded onto the host. Using the docker run command, install the {{page.netscaler-cpx-short}} instance with the default {{page.netscaler-cpx-short}} configuration.
Important:
If you have downloaded {{page.netscaler-cpx-short}} Express from https://www.citrix.com/products/netscaler-adc/cpx-express.html, make sure that you read and understand the End User License Agreement (EULA) available at: https://www.citrix.com/products/netscaler-adc/cpx-express.html and accept the EULA while deploying the {{page.netscaler-cpx-short}} instance.
Install the {{page.netscaler-cpx-short}} instance on the Docker container by using the following docker run command:
docker run -dt -P --privileged=true --net=host –e NS_NETMODE=”HOST” -e CPX_CORES=<number of cores> --name <container_name> --ulimit core=-1 -e CPX_NW_DEV='<INTERFACES>' -e CPX_CONFIG=’{“YIELD”:”NO”}’ -e LS_IP=<LS_IP_ADDRESS> -e LS_PORT=<LS_PORT> e PLATFORM=CP1000 -v <host_dir>:/cpx <REPOSITORY>:<TAG>docker run -dt --privileged=true --net=host -e NS_NETMODE="HOST" -e CPX_NW_DEV='eth1 eth2' -e CPX_CORES=5 –e CPX_CONFIG='{"YIELD":"No"}' -e LS_IP=10.102.38.134 -e PLATFORM=CP1000 -v /var/cpx:/cpx --name cpx_host cpx:12.1-48.xx
This example creates a container named mycpx based on the {{page.netscaler-cpx-short}} Docker image.
The -P parameter is mandatory. It tells Docker to map the ports exposed in the container by the {{page.netscaler-cpx-short}} Docker image. That means map ports 9080, 22, 9443, and 161/UDP, to the ports on the Docker host that are randomly selected from the user defined range. This mapping is done to avoid conflicts. If you later create multiple {{page.netscaler-cpx-short}} containers on the same Docker host. The port mappings are dynamic and are set each time the container is started or restarted. The ports are used as follows:
  • 9080 is used for HTTP
  • 9443 is used for HTTPs
  • 22 used for SSH
  • 161/UDP is used for SNMP.
If you want static port mappings, use the -p parameter to set them manually.
The --privileged=true option is used to run the container in privileged mode. If you are running the {{page.netscaler-cpx-short}} with multiple cores then you need to provide all the system privileges to the {{page.netscaler-cpx-short}}. If you want to run the {{page.netscaler-cpx-short}} with a single core then instead of this option you must use the --cap-add=NET_ADMIN option. The --cap-add=NET_ADMIN option enables you to run the {{page.netscaler-cpx-short}} container with full network privileges.
The**--net=host is a standard docker run command option that specifies that the container is running in the host network stack and has access to all the network devices.
Note
If you are running {{page.netscaler-cpx-short}} in bridge or none network, ignore this option.
The -e NS_NETMODE="HOST" is a {{page.netscaler-cpx-short}} specific environment variable that allows you to specify that the {{page.netscaler-cpx-short}} is started in host mode. Once {{page.netscaler-cpx-short}} starts in host mode it configures four default iptable rules on the host machine for management access to the {{page.netscaler-cpx-short}}. It uses the following ports:
  • 9995 for HTTP
  • 9996 for HTTPS
  • 9997 for SSH
  • 9998 for SNMP
If you want to specify different ports, you can use the following environment variables:
  • -e NS_HTTP_PORT=
  • -e NS_HTTPS_PORT=
  • -e NS_SSH_PORT=
  • -e NS_SNMP_PORT=
Note
If you are running {{page.netscaler-cpx-short}} in bridge or none network, ignore this environment variable.
The -e CPX_CORES is an optional {{page.netscaler-cpx-short}} specific environment variable. You can use it to improve the performance of the {{page.netscaler-cpx-short}} instance by defining the number of processing engines that you want the {{page.netscaler-cpx-short}} container to start.
Note
For every additional processing engine you add, make sure that the Docker host contains the equivalent number of vCPUs and amount of memory in GB. For example, if you want to add 4 processing engines, then the Docker host must contain 4 vCPUs and 4 GB of memory.
The -e EULA = yes is a mandatory {{page.netscaler-cpx-short}} specific environment variable, which is required to verify that you have read and understand the End User License Agreement (EULA) available at: https://www.citrix.com/products/netscaler-adc/cpx-express.html.
The -e PLATFORM=CP1000 parameter specifies the {{page.netscaler-cpx-short}} license type.
If you are running Docker in a host network, you can assign dedicated network interfaces to the {{page.netscaler-cpx-short}} container using the -e CPX_NW_DEV environment variable. You need to define the network interfaces separated by a whitespace. The network interfaces that you define are held by the {{page.netscaler-cpx-short}} container until you uninstall the {{page.netscaler-cpx-short}} container. When the {{page.netscaler-cpx-short}} container is provisioned all the assigned network interfaces are added to the NetScaler networking namespace.
Note
If you are running {{page.netscaler-cpx-short}} in a bridge network you may change the container network, such as, configure another network connection to the container or remove an existing network. Then make sure that you restart the {{page.netscaler-cpx-short}} container to use the updated network.
docker run -dt --privileged=true --net=host -e NS_NETMODE="HOST" -e EULA=yes -e CPX_NW_DEV='eth1 eth2' -e CPX_CORES=5 -e PLATFORM=CP1000 --name cpx_host cpx:12.0-53.x
The -e CPX_CONFIG is a {{page.netscaler-cpx-short}} specific environment variable that enables you to control the throughput performance of the {{page.netscaler-cpx-short}} container. When the {{page.netscaler-cpx-short}} does not receive any incoming traffic to process, it yields the CPU during this idle time, hence resulting in low throughput performance. You can use the CPX_CONFIG environment variable to control the throughput performance of the {{page.netscaler-cpx-short}} container in such scenarios. You need to provide the following values to the CPX_CONFIG environment variable in JSON format:
  • If you want the {{page.netscaler-cpx-short}} container to yield CPU in idle scenarios, define {"YIELD” : “Yes”}
  • If you want the {{page.netscaler-cpx-short}} container to avoid yielding the CPU in idle scenarios so that you can get high throughput performance, define {“YIELD” : “No”}
docker run -dt --privileged=true --net=host -e NS_NETMODE="HOST" -e EULA=yes -e CPX_CORES=5 –e CPX_CONFIG='{"YIELD":"No"}' -e PLATFORM=CP1000 --name cpx_host cpx:12.0-51.xdocker run -dt --privileged=true --net=host -e NS_NETMODE="HOST" -e EULA=yes -e CPX_CORES=5 –e CPX_CONFIG='{"YIELD":"Yes"}' -e PLATFORM=CP1000 --name cpx_host cpx:12.0-51.xx
The –v parameter is an optional parameter that specifies the mount point of the {{page.netscaler-cpx-short}} mount directory, /cpx. A mount point is a directory on the host, in which you mount the /cpx directory. The /cpx directory stores the logs, configuration files, SSL certificates, and core dump files. In the example, the mount point is /var/cpx and the {{page.netscaler-cpx-short}} mount directory is /cpx.
If you purchased a license or have an evaluation license, you can upload the license to a license server and specify the license server location with the docker run command, by using the -e LS_IP=<LS_IP_ADDRESS> -e LS_PORT=<LS_PORT> parameter. In this case, you do not need to accept the EULA.
docker run -dt --privileged=true --net=host -e NS_NETMODE="HOST" -e CPX_CORES=5 –e CPX_CONFIG='{"YIELD":"No"}' -e LS_IP=10.102.38.134 -e PLATFORM=CP1000 --name cpx_host cpx:12.0-51.xx
Where:
  • LS_IP_ADDRESS is the IP address of the license server.
  • LS_PORT is the port of the license server.
You can view the images running on your system and the ports mapped to the standard ports by using the command: docker ps

Deploying {{page.netscaler-cpx-short}} Instances by Using Docker Compose

You can use the Compose tool of Docker to provision a single {{page.netscaler-cpx-short}} instance or multiple {{page.netscaler-cpx-short}} instances. To provision {{page.netscaler-cpx-short}} instances by using Compose, you must first write a compose file. This file specifies the {{page.netscaler-cpx-short}} image, the ports that you want to open for the {{page.netscaler-cpx-short}} instance, and the privileges for your {{page.netscaler-cpx-short}} instance.
Important
Make sure that you have installed Docker Compose tool on the host.
To provision multiple {{page.netscaler-cpx-short}} instances:
  1. Write a compose file, where:
  • \&lt;service-name> is the name of the service you want to provision.
  • image:\&lt;repository>:\&lt;tag> denotes the repository and the versions of the {{page.netscaler-cpx-short}} image.
  • privileged: true provides all root privileges to the {{page.netscaler-cpx-short}} instance.
  • cap_add provides network privileges to the {{page.netscaler-cpx-short}} instance.
  • \&lt;host_directory_path> denotes the directory on the docker host that you want to mount for the {{page.netscaler-cpx-short}} instance.
  • \&lt;number_processing_engine> is the number of processing engines that you want the {{page.netscaler-cpx-short}} instance to start. For every additional processing engine, make sure that the Docker host contains the equivalent number of vCPUs and amount of memory in GB. For example, if you want to add 4 processing engines, then the Docker host must contain 4 vCPUs and 4 GB of memory.
The compose file generally follows a format similar to:
<service-name>:
container_name:
image: <repository>:<tag>
ports:
    - 22
    - 9080
    - 9443
    - 161/udp
    - 35021-35030
tty: true
cap_add:
    - NET_ADMIN
ulimits:
    core: -1
volumes:
    - <host_directory_path>:/cpx
environment:
    - EULA=yes
    - CPX_CORES=<number_processing_engine>
    - CPX_CONFIG='{"YIELD":"Yes"}'CPX_0:
container_name: CPX_0
image: cpx:12.0-53.xx
ports:
    -  9443
    -  22
    -  9080
    -  161/udp
    -  35021-35030
tty: true
cap_add:
    - NET_ADMIN
ulimits:
    core: -1
volumes:
    - /root/test:/cpx
environment:
    -  CPX_CORES=2
    -  EULA=yes
If you want to provision a single {{page.netscaler-cpx-short}} instance, you must add the following line to the compose file: container_name:<name_of_container>
Run the following command to provision multiple {{page.netscaler-cpx-short}} instances: docker-compose -f <compose_file_name> scale <service-name>=<number of instances> up –d docker-compose -f docker-compose.yml scale cpxlb=3 up –d
If you want to provision a single {{page.netscaler-cpx-short}} instance, run the following command: docker-compose -f <compose_file_name> up –d