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.jsonin your project directory alongsidedocker-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 updateand the REST init request accept both; a token issued for GridGain 8 is rejected. The examples below use a file namedgridgain-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 execon 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.
Start the Cluster
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.
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.
Related
How to Manage Cluster Lifecycle with the REST API - Monitor startup, initialize, and verify cluster health using REST endpoints.
Start Your Local GridGain 9 Development Cluster - Tutorial that walks through this setup with deeper context, loads the Music Store dataset, and introduces cluster concepts.
How to Work with the GridGain CLI - Interactive SQL, cluster inspection, output formatting, and profiles.
This page is: Copyright © 2026 MariaDB. All rights reserved.
Last updated
Was this helpful?

