For the complete documentation index, see llms.txt. This page is also available as Markdown.

How to Start a Cluster With Docker Compose

Start a 3-node GridGain 9 cluster for development using Docker Compose.

Prerequisites

  • Docker 20.10 or later

  • Docker Compose 2.23.1 or later (ships with Docker Desktop)

  • curl and jq for verifying cluster health

  • Ports 10300-10302 and 10800-10802 available on your machine

  • 12 GB of available RAM for three cluster nodes (4 GB minimum; see the memory note in Step 1)

  • GridGain 9 only: A GridGain 9 license file. If you are interested in trying out GridGain 9, contact our support. Save the license file as gridgain-license.json in your project directory alongside docker-compose.yml. The license can be either a JSON license file or a license token issued by MariaDB (a single line of text in JWT format). cluster init --license, license update and the REST init request accept both; a token issued for GridGain 8 is rejected. The examples below use a file named gridgain-license.json; if you have a token, substitute the name of the file you saved it in.

Overview

This guide walks you through starting a 3-node development cluster on your local machine with Docker Compose. By the end, you will have a running cluster that accepts client connections on ports 10800-10802 and exposes a REST management API on ports 10300-10302.

GridGain 9 has a distributed architecture that you manage through the REST API and the CLI. The cluster lifecycle is: start nodes, initialize them into a cluster, then connect.

You have two tools for managing the cluster once the containers are running:

  • REST API (port 10300) accepts HTTP requests for cluster initialization, health checks, and configuration. It is available as soon as a node starts, even before the cluster is initialized. Use this when you want scriptable, automatable management.

  • CLI tool is an interactive command-line shell that communicates with the cluster through the REST API. It is bundled inside the server image, so you access it via docker exec on any running node. Use it for interactive sessions, SQL queries, or one-off administration. For a deeper walkthrough, see How to Work with the GridGain CLI.

Each step shows both management approaches where they differ.

Create a Docker Compose File

Create a directory for your project and add a file named docker-compose.yml with the following content.

Ensure your gridgain-license.json file (from the prerequisites) is in the same directory where you create docker-compose.yml.

The image names use gridgain/gridgain9, and the node configuration mounts to /opt/gridgain/etc/. The GridGain CLI is bundled inside the server image at /opt/gridgain9cli/bin/gridgain9.

Port 3344 handles internal cluster communication between nodes. Docker's internal network routes this traffic, so you don't need to expose it to the host.

Reduce JVM_MAX_MEM and JVM_MIN_MEM to 1g if your machine has less than 16 GB of RAM. Each node will use approximately 1 GB instead of 4 GB. Performance will be adequate for development and tutorial workloads.

Start the Cluster

The compose file uses the latest tag. docker compose up -d does not refresh an image that is already on your machine, so if you pulled GridGain 9 before, run docker compose pull first to get the current release.

Start the cluster:

Expected output:

The nodes need a few seconds to discover each other over port 3344 and form a physical topology. Verify all three containers are running:

Expected output:

Initialize the Cluster

At this point, the nodes are running and can see each other, but they are not yet a cluster. Initialization is a one-time step that elects a leader, designates which nodes store cluster metadata, and opens client connection ports (10800). Until you initialize, the REST API on port 10300 is the only way to interact with the nodes.

Choose your preferred management tool below. Both accomplish the same result.

Send the initialization request to any node's REST endpoint. The REST API is available on all three nodes (ports 10300, 10301, 10302), but you only need to send the init request once.

GridGain 9 requires the license content in the init request. Load the license file into a shell variable first. jq -Rs reads the file and encodes it as a JSON string with proper escaping:

Initialize the cluster with the license:

A successful initialization returns HTTP 200 with an empty response body.

Open the CLI inside a running node with docker exec. The CLI is bundled in the server image.

First, copy the license file into the container:

Then open the CLI:

At the CLI prompt, connect to the local node and initialize with the license file:

Expected output:

Type exit; to leave the CLI.

Allow a few seconds for the nodes to elect a leader and synchronize metadata before verifying.

Verify Cluster Health

Once the cluster is initialized, confirm that all three nodes joined successfully.

Expected output:

Both cmgNodes (cluster management group) and msNodes (metastorage nodes) should list all three nodes. The igniteVersion field reflects the product version.

At the CLI prompt:

Expected output:

For a detailed node list, use:

This lists all nodes with their names, addresses, and IDs.

Type exit; to leave the CLI.

Stopping and Restarting

These are the Docker Compose lifecycle commands for the cluster.

Stop the cluster (preserves data):

This stops the containers without removing them. Data, cluster state, and initialization all persist.

Restart a stopped cluster:

The nodes rejoin the existing cluster automatically. You do not need to re-initialize. Client connections on port 10800 become available once the nodes finish starting (typically 15-30 seconds). This same command also works after docker compose down to create a fresh cluster (which will require re-initialization).

Remove the cluster (destroys data):

This removes all containers and the default network, destroying all data. The next docker compose up -d starts a fresh cluster that requires re-initialization.

Remove the cluster and all volumes:

This also removes named volumes for a completely clean state.

Troubleshooting

These are the common issues and their fixes.

Port conflict on startup

docker compose up -d fails with Bind for 0.0.0.0:10300 failed: port is already allocated.

Another process is using one of the required ports. Identify it:

Stop the conflicting process, or change the host port mapping in docker-compose.yml. For example, map to port 10400 instead:

Adjust all subsequent commands to use the new port number.

Initialization timeout

The curl command to /management/v1/cluster/init hangs or returns connection refused.

The nodes are not ready yet. Check that all containers are running:

If a container shows Restarting or Exited, check its logs:

Wait for the REST API to become available (30-60 seconds after startup):

When this returns a JSON response, the node is ready for initialization.

Fewer than 3 nodes in cluster state

/management/v1/cluster/state shows fewer than 3 nodes in cmgNodes or msNodes.

The cluster was initialized before all nodes discovered each other. In a development environment, the safest fix is to start over:

Wait 30-60 seconds for all nodes to discover each other, then re-initialize.

Client connection refused on port 10800

An application connecting to localhost:10800 gets Connection refused after the containers are running.

Client ports open only after cluster initialization. Verify the cluster is initialized:

If this returns null or an error, the cluster has not been initialized. Complete the Initialize the Cluster step above.

GridGain 9: License error during REST API initialization

GridGain 9 only. The REST API returns HTTP 400 with a message about a missing or invalid license.

Verify that gridgain-license.json exists in the same directory as docker-compose.yml:

Verify the file contains valid JSON (this check applies to a JSON license file; a license token is a single line of text, not JSON):

The license field in the curl command must be a JSON-encoded string of the file contents, not the filename. Use LICENSE=$(jq -Rs . gridgain-license.json) to load the license into a variable as shown in the initialization step.

GridGain 9: License error during CLI initialization

GridGain 9 only. The CLI returns an error about a missing license when running cluster init.

Verify the license file was copied into the container:

If the file is missing, copy it again:

Use the --license=/opt/gridgain9cli/license.json flag with the cluster init command.

Your cluster is now accepting client connections on ports 10800-10802. You can connect with any GridGain thin client driver, JDBC (jdbc:ignite:thin://localhost:10800), or ODBC.

This page is: Copyright © 2026 MariaDB. All rights reserved.

spinner

Last updated

Was this helpful?