This post details how to deploy and run the nsq binaries inside Docker containers.

There is a single, minimal nsq image that contains all of the NSQ binaries. Each binary can be run by specifying the binary as the command when running Docker. The basic format is:

docker run nsqio/nsq /<command>

Note the / before the command. For example:

docker run nsqio/nsq /nsq_to_file

Run nsqlookupd

docker pull nsqio/nsq
docker run --name lookupd -p 4160:4160 -p 4161:4161 nsqio/nsq /nsqlookupd

Run nsqd

First, get the docker host’s ip:

ifconfig | grep addr

Second, run the nsqd container:

docker pull nsqio/nsq
docker run --name nsqd -p 4150:4150 -p 4151:4151 \
    nsqio/nsq /nsqd \
    --broadcast-address=<host> \

Set the --lookupd-tcp-address flag to the host’s IP and the TCP port of previously run nsqlookupd, i.e. dockerIP:4160:

For example, given a host IP of

docker run --name nsqd -p 4150:4150 -p 4151:4151 \
    nsqio/nsq /nsqd \
    --broadcast-address= \

Note that this uses port 4160, the port exposed when we started the nsqlookupd container (which also happens to be the default port for nsqlookupd).

If you want to use a non-default port, change the -p parameter:

docker run --name nsqlookupd -p 5160:4160 -p 5161:4161 nsqio/nsq /nsqlookupd

That will make nsqlookupd available on the docker host’s IP on the ports 5160 and 5161.

Using TLS

To use TLS with containerized NSQ binaries, you need to include the certificate file, the private key, and the root CA file. The Docker image has a volume mount available at /etc/ssl/certs/ available for this purpose. Mount a host directory containing the files to the volume, then specify the files in the command line, as usual:

docker run -p 4150:4150 -p 4151:4151 -p 4152:4152 -v /home/docker/certs:/etc/ssl/certs \
    nsqio/nsq /nsqd \
    --tls-root-ca-file=/etc/ssl/certs/certs.crt \
    --tls-cert=/etc/ssl/certs/cert.pem \
    --tls-key=/etc/ssl/certs/key.pem \
    --tls-required=true \

This will load the certificates from /home/docker/certs into the Docker container to use when running.

Persisting NSQ Data

To store nsqd data on the host disk, use the /data volume as your data directory, which lets you mount to a data-only Docker container or mount to a host-directory:

docker run nsqio/nsq /nsqd \

Using docker-compose

To start nsqd, nsqlookupd, and nsqadmin together using docker-compose then create a docker-compose.yml.

version: '2'
    image: nsqio/nsq
    command: /nsqlookupd
      - "4160"
      - "4161"
    image: nsqio/nsq
    command: /nsqd --lookupd-tcp-address=nsqlookupd:4160
      - "4150"
      - "4151"
    image: nsqio/nsq
    command: /nsqadmin --lookupd-http-address=nsqlookupd:4161
      - "4171"

To start run the following command from the same directory as the docker-compose.yml created previously.

docker-compose up -d

A private network will be created and three containers will be started using the private network. On the local host each container will have a random port mapped to ports exposed in the docker-compose.yml.

To view the running containers status and mapped ports.

docker-compose ps

To see the logs from the running containers.

docker-compose logs

Assuming that the nsqlookupd had host port 31001 mapped to the container port 4161 a simple ping could be performed using curl.