A newer version of this documentation is available.

View Latest

Docker Hub

There are several Docker configuration scenarios for Couchbase Server deployments. The most common one is using single host and single container.
Use deployment with Docker for development and testing purposes only.

Couchbase Server communicates on a number of different ports. In addition, it is not supported for nodes in a cluster that are behind any kind of NAT.

For these reasons, Docker’s default networking configuration is not ideally suited to Couchbase Server deployments. There are several deployment scenarios that Docker can easily support, and that are described along with recommended network arrangements for each.

Volumes

A Couchbase Server Docker container will write all persistent and node-specific data under the directory /opt/couchbase/var. It is recommended to map this directory to a directory on the host file system using the -v option to docker run and for the following reasons:

Persistence

Storing /opt/couchbase/var outside the container allows you to delete the container and recreate it later. You can even update to a container running a later point release of Couchbase Server without losing your data.

Performance

In a standard Docker environment using a union file system, leaving /opt/couchbase/var inside the container will result in some amount of performance degradation.

All of the sample commands below assume that you are using volumes mapped to host directories.

SELinux workaround

If you have SELinux enabled, mounting the host volumes in a container requires an extra step. Assuming you are mounting the ~/couchbase directory on the host file system, you need to run the following command once before running your first container on that host:

 mkdir ~/couchbase && chcon -Rt svirt_sandbox_file_t ~/couchbase

Ulimits

Couchbase Server normally expects the following changes to ulimits:

ulimit -n 40960        # nofile: max number of open files
ulimit -c unlimited    # core: max core file size
ulimit -l unlimited    # memlock: maximum locked-in-memory address space

These ulimit settings are necessary when running under heavy load. If you are just doing light testing and development, you can omit these settings, and everything will still work.

To set the ulimits in your container, you will need to run Couchbase Docker containers with the following additional --ulimit flags:

docker run -d --ulimit nofile=40960:40960 --ulimit core=100000000:100000000 --ulimit memlock=100000000:100000000 couchbase/server

Since unlimited is not supported as a value, it sets the core and memlock values to 100 GB. If your system has more than 100 GB RAM, you will want to increase this value to match the available RAM on the system.

The --ulimit flags only work on Docker 1.6 or later.