Configure DataStax Enterprise (DSE) Docker containers

There are several ways to customize the configuration and deployment of Docker containers for DSE and related software:

  • Modify the Docker host and the container environment.

  • Modify the software running in the container.

  • Use docker compose scripts to automate deployments of multiple containers.

  • Build custom images.

If the configuration options provided by the DataStax base images aren’t sufficient for your use case, you can build custom images with the desired configuration settings.

For more advanced use cases, you can use docker compose scripts to automate deployments of multiple containers, and you can build custom images.

Options for docker run and docker compose

You can pass container configuration options on the command line and in configuration files when you start the container with docker run or docker compose.

Option Description

-d

Recommended. Starts the container in the background.

-e

Required. Sets required and optional environment variables to accept the licensing agreement and change the initial configuration. For more information, see Use environment variables.

The DS_LICENSE environment variable is required to start the software.

-p

Open container ports on the host to allow remote access to DSE, DSE OpsCenter, and DataStax Studio containers.

-v

Mount a directory on the local host to a container volume to manage configuration or preserve data.

--link

Link a DSE container to a container running a related service, such as DSE OpsCenter or DataStax Studio. For example, --link my-opscenter:opscenter or --link my-dse.

--name

Assign a name to the container.

Other options

For information about other options you can use with docker run and docker compose, see the following:

DSE container configuration

In addition to general container startup options, you can configure specific DSE settings in the following ways:

Use the DSE configuration volume

DataStax DSE Docker images include a startup script that replaces the DSE configuration files in the /config volume directory with configuration files in the default location on the container. This allows you to provide custom configuration values without building custom images or relying on host volumes.

  1. Create a directory on your local host to store the configuration files.

  2. Add the configuration files to replace in the container.

    Your configuration files must correspond to configuration files specified in the image, and they must include all required values.

    For example, to replace the default cassandra.yaml, your custom configuration file must be named cassandra.yaml and it must include, at minimum, all required values for a functional cassandra.yaml file.

    If you are also running DSE OpsCenter or DataStax Studio containers, you can include those configuration files as well, such as opscenterd.conf. For a full list of supported configuration files, see the Container configuration templates.

    Changing unsupported configuration files, such as SSL key management files, requires an additional host volume or a custom image.

  3. Mount the exposed /config volume to your local directory when you start the container.

    The following example mounts /config to the local path /dse/conf:

    docker run -e DS_LICENSE=accept --name my-dse -v /dse/config:/config \
-d datastax/dse-server:DSE_VERSION

  4. If you change the configuration files, restart the container to propagate the changes to the database:

    docker restart container_name

    Restarting the container restarts DSE.

Use environment variables

Use environment variables to change the Docker image configuration at runtime. You can use the -e option with docker run, or set values in your docker compose script.

DSE uses the default values defined for the environment variables unless explicitly set at runtime or overridden with the DSE_AUTO_CONF_OFF environment variable.

Environment variables override the same values set in configuration files.

Variable Type Description Default

DS_LICENSE

string

If set to accept, shows the DataStax license and implies that you accept the terms of the license agreement.

Must be set to accept to start the software.

unset

LISTEN_ADDRESS

IP_address

IP address to listen for connections from other nodes.

The container IP address

BROADCAST_ADDRESS

IP_address

IP address to advertise to other nodes.

If not set, the default value is the LISTEN_ADDRESS.

NATIVE_TRANSPORT_ADDRESS

IP_address

IP address to listen for client and driver connections.

0.0.0.0

NATIVE_TRANSPORT_BROADCAST_ADDRESS

IP_address

IP address to advertise to clients and drivers.

If not set, the default value is the BROADCAST_ADDRESS.

SEEDS

IP_address

Comma-delimited list of seed nodes for the cluster.

If not set, the default value is the node’s BROADCAST_ADDRESS.

START_RPC

Boolean

Whether to start the Thrift RPC server.

If not set, the default value is preserved in cassandra.yaml.

CLUSTER_NAME

string

Name of the cluster.

Test Cluster

NUM_TOKENS

int

Number of tokens randomly assigned to the node.

8

DC

string

Datacenter name

Cassandra

RACK

string

Rack name

rack1

OPSCENTER_IP

IP_address

Address of a DSE OpsCenter instance to use with the DSE container.

If the DSE container is linked to a DSE OpsCenter container named opscenter, that container’s address is automatically set as the OPSCENTER_IP.

JVM_EXTRA_OPTS

string

Sets a custom value for the JVM heap using -Xmx and -Xms. Recommended to explicitly set to ensure appropriate resource allocation.

25 percent of the physical RAM of the Docker host.

LANG

string

Sets a custom locale.

SNITCH

string

Sets the snitch implementation this node will use.

The value is set in the endpoint_snitch parameter in cassandra.yaml.

DSE_AUTO_CONF_OFF

string

Prevents environment variables from overriding values in specified configuration files.

Provide a comma-separated list of filenames that can include cassandra.yaml, cassandra-rackdc.properties, or all (both files). Values in the specified files cannot be surpassed by environmental variables.

false

Persist volumes

Persisted storage volumes for Docker containers allow you to delete and re-create containers without losing data.

Volumes that aren’t mounted from the local host are destroyed when the container is removed.

DataStax Docker images expose the following volumes, which you can mount to directories on the local host:

Exposed volumes
Container Directory Description

DSE

/var/lib/cassandra

Transactional database data

DSE

/var/lib/spark

DSE Analytics (Apache Spark™) data, if starting the container with -k

DSE

/var/lib/dsefs

DSEFS data

DSE

/var/log/cassandra

Transactional database logs

DSE

/var/log/spark

DSE Analytics logs

DSE, DSE OpsCenter, DataStax Studio

/config

Custom configuration files

DSE OpsCenter

/var/lib/opscenter

DSE OpsCenter data

DataStax Studio

/var/lib/datastax-studio

DataStax Studio data

To persist the data in a container volume, mount the volume to a local directory on the Docker host using the -v option. You must create the local directory before mounting the volume.

docker run -v LOCAL_DIRECTORY:CONTAINER_VOLUME

The following example mounts the /var/lib/cassandra volume to a local /dse/data directory on the Docker host. All subdirectories of the mounted volume are created automatically and persisted in the local directory. For /var/lib/cassandra, this includes the /data, /commit_logs, and /saved_caches subdirectories.

docker run -e DS_LICENSE=accept --name my-dse -v /dse/data:/var/lib/cassandra

Use Docker compose for automated provisioning

You can deploy multiple Docker containers using Docker Compose scripts to automate bootstrapping single and multi-node clusters with DataStax containers.

You can use the following example compose.yml files as a starting point for your container deployments:

docker-compose.yml (DSE)
version: '2'
services:
  seed_node:
    image: "datastax/dse-server"
    environment:
      - DS_LICENSE=accept
    # Allow DSE to lock memory with mlock
    cap_add:
    - IPC_LOCK
    ulimits:
      memlock: -1
  node:
    image: "datastax/dse-server"
    environment:
      - DS_LICENSE=accept
      - SEEDS=seed_node
    links:
      - seed_node
    # Allow DSE to lock memory with mlock
    cap_add:
    - IPC_LOCK
    ulimits:
      memlock: -1
docker-compose.opscenter.yml
version: '2'
services:
  opscenter:
    image: "datastax/dse-opscenter"
    ports:
      - 8888:8888
    environment:
      - DS_LICENSE=accept
  seed_node:
    links:
      - opscenter
  node:
    links:
      - opscenter
docker-compose.studio.yml
version: '2'
services:
  studio:
    image: "datastax/dse-studio"
    environment:
      - DS_LICENSE=accept
    ports:
      - 9091:9091

The following examples demonstrate single-node and three-node container deployments:

Single node configuration

To bootstrap a single-node cluster, use the docker run command and specify the version of DSE to install, plus any additional options.

docker run -e DS_LICENSE=accept -d datastax/dse-server:version \
options
Single node configuration with DataStax Studio
docker compose -f docker-compose.yml -f docker-compose.studio.yml \
up -d --scale node0
Three node configuration

When creating multiple nodes, use the node parameter to bootstrap one node at a time. For example, the first node is node0, the second node is node1, and the third node is node2.

Wait for each node to finish bootstrapping before running docker-compose for the next node.

# Make sure node1, the seed node, is up before bringing up other nodes
docker compose -f docker-compose.yml up -d --scale node0
# Wait until the seed node is up before bringing up more nodes
(docker compose logs -f node1 &) | grep -q "Created default superuser role"
docker compose -f docker-compose.yml up -d --scale node1
(docker compose logs -f node1 &) | grep -q "Created default superuser role"
docker compose -f docker-compose.yml up -d --scale node2
Three node configuration with DSE OpsCenter
docker compose -f docker-compose.yml -f docker-compose.opscenter.yml \
up -d --scale node0
# Make sure node1, the seed node, is up before bringing up other nodes
(docker compose logs -f node0 &) | grep -q "Created default superuser role"
docker compose -f docker-compose.yml up -d --scale node1
(docker compose logs -f node1 &) | grep -q "Created default superuser role"
docker compose -f docker-compose.yml up -d --scale node2
Three node configuration with DSE OpsCenter and DataStax Studio
docker compose -f docker-compose.yml -f docker-compose.opscenter.yml \
-f docker-compose.studio.yml up -d --scale node0
# Make sure node1, the seed node, is up before bringing up other nodes
(docker compose logs -f node0 &) | grep -q "Created default superuser role"
docker compose -f docker-compose.yml up -d --scale node1
(docker compose logs -f node1 &) | grep -q "Created default superuser role"
docker compose -f docker-compose.yml up -d --scale node2

Build custom DataStax Docker images

You can use DataStax source code to build a custom Docker image for your environment:

  1. Clone the DataStax Docker images examples Github repository, which includes sample Docker files and build scripts.

    Gradle is used to build the images.

    To get the list of available Gradle tasks, run ./gradlew tasks from the root of the repository.

  2. Make any desired configuration changes to the images.

    DataStax uses a common base image for all products. To customize the operating system or install additional packages, modify the base/Dockerfile. The DataStax base images use OpenJDK due to the end of public updates for Oracle JDK.

  3. Build one or more images.

    By default, the builds download the latest DataStax tarballs from the DataStax downloads server. Optionally, you can specify a version to build. You can also build multiple images of the same product.

    Build one image
    ./gradlew
    Build all images
    ./gradlew buildImages
    Build one image at a specific version

    Specify the product and version when invoking the Gradle task:

    ./gradlew buildPRODUCTVERSIONImage

    For example:

    ./gradlew buildServer6.0.6Image
    Build multiple images with specific versions

    Specify each build with the desired product and version when invoking the Gradle task. For example:

    ./gradlew buildServer6.0.6Image buildOpscenter6.5.0Image
    Build multiple product versions

    To support multiple product versions without duplicating files, Docker build contexts are generated from source folders that contain FreeMarker templates (files with .ftl extensions).

    To customize the products or use multiple product versions, modify the templates in their corresponding product folder in the repository.

    The following conventions are used:

    • Docker build contexts are generated from self-describing product folders. For example, server, opscenter, and studio.

    • All files without the .ftl extension are copied to the build context.

    • Files with .ftl extensions are processed as FreeMarker templates:

      • Template directives are written using angle bracket syntax.

      • Square bracket syntax is used for interpolations.

      • The processed files are copied to the build context without .ftl extension. For example, Dockerfile.ftl is copied as Dockerfile.

    • FreeMarker templates use the version variable:

      • version.major returns product version major number

      • version.minor returns product version minor number

      • version.bugfix returns product version bugfix number

      • version.lowerThan('x.y.z') function returns true if version is semantically lower than x.y.z

      • version.greaterEqualThan('x.y.z') function returns true if version is semantically greater than or equal to x.y.z.

Was this helpful?

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2026 | Privacy policy | Terms of use |  Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: Contact IBM