How to Start a GridGain 9 Cluster in Docker
This guide walks you through the process of setting up and running a GridGain 9 cluster using Docker containers. Follow these steps to get a three-node cluster up and running quickly.
Prerequisites
- 
Up-to-date Docker and Docker Compose installed on your system 
- 
Basic familiarity with command-line operations 
- 
The code editor of your choice (VS Code, IntelliJ IDEA, etc.) 
Step 1: Create a Docker Compose Configuration
- 
Create a file named docker-compose.ymlin your project directory:
#  Copyright (C) GridGain Systems. All Rights Reserved.
#  _________        _____ __________________        _____
#  __  ____/___________(_)______  /__  ____/______ ____(_)_______
#  _  / __  __  ___/__  / _  __  / _  / __  _  __ `/__  / __  __ \
#  / /_/ /  _  /    _  /  / /_/ /  / /_/ /  / /_/ / _  /  _  / / /
#  \____/   /_/     /_/   \_,__/   \____/   \__,_/  /_/   /_/ /_/
name: gridgain9
x-gridgain-def: &gridgain-def
  image: gridgain/gridgain9:9.1.11
  environment:
    JVM_MAX_MEM: "4g"
    JVM_MIN_MEM: "4g"
    BOOTSTRAP_NODE_CONFIG: /opt/gridgain/etc/gridgain-config.conf
  configs:
    - source: node_config
      target: /opt/gridgain/etc/gridgain-config.conf
      mode: 0644
services:
  node1:
    <<: *gridgain-def
    command: --node-name node1
    ports:
      - "10300:10300"
      - "10800:10800"
  node2:
    <<: *gridgain-def
    command: --node-name node2
    ports:
      - "10301:10300"
      - "10801:10800"
  node3:
    <<: *gridgain-def
    command: --node-name node3
    ports:
      - "10302:10300"
      - "10802:10800"
configs:
  node_config:
    content: |
      ignite {
        network {
          port: 3344
          nodeFinder.netClusterNodes = ["node1:3344", "node2:3344", "node3:3344"]
        }
      }Step 2: Start the Ignite Cluster
- 
Open a terminal in the directory containing your docker-compose.ymlfile
- 
Run the following command to start the cluster: docker compose up -d
- 
Verify that all containers are running: docker compose psHere is how the command output may look: NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS gridgain9-node1-1 gridgain/gridgain9:9.1.11 "docker-entrypoint.s…" node1 13 seconds ago Up 9 seconds 0.0.0.0:10300->10300/tcp, 3344/tcp, 0.0.0.0:10800->10800/tcp gridgain9-node2-1 gridgain/gridgain9:9.1.11 "docker-entrypoint.s…" node2 13 seconds ago Up 9 seconds 3344/tcp, 0.0.0.0:10301->10300/tcp, 0.0.0.0:10801->10800/tcp gridgain9-node3-1 gridgain/gridgain9:9.1.11 "docker-entrypoint.s…" node3 13 seconds ago Up 9 seconds 3344/tcp, 0.0.0.0:10302->10300/tcp, 0.0.0.0:10802->10800/tcp
Your nodes are now running, but the cluster is not initialized.
Step 3: Initialize the Cluster
- 
Copy your license file into your project directory. 
- 
Start the Ignite CLI in Docker: docker run --rm -it --network=host -v /opt/etc/license.json:/opt/gridgain/etc/license.json gridgain/gridgain9:9.1.11 cli
- 
Inside the CLI, connect to one of the nodes: connect http://localhost:10300
- 
Confirm the connection to the default node in the CLI tool. 
- 
Initialize the cluster with a name and license: cluster init --name=GridGain --license=/opt/gridgain/etc/license.json
The output from this step should be similar to this:
  _________        _____ __________________        _____
  __  ____/___________(_)______  /__  ____/______ ____(_)_______
  _  / __  __  ___/__  / _  __  / _  / __  _  __ `/__  / __  __ \
  / /_/ /  _  /    _  /  / /_/ /  / /_/ /  / /_/ / _  /  _  / / /
  \____/   /_/     /_/   \_,__/   \____/   \__,_/  /_/   /_/ /_/
                      GridGain CLI version 9.1.11
You appear to have not connected to any node yet. Do you want to connect to the default node http://localhost:10300? [Y/n]
Connected to http://localhost:10300
The cluster is not initialized. Run cluster init command to initialize it.
[node1]> cluster init --name=GridGain --license=/opt/gridgain/etc/license.json
Cluster was initialized successfully
[node1]>Step 4: Verify Your Cluster
- 
Use the cluster statusCLI command to verify your cluster is running correctly.cluster statusThe output should look similar to this: [name: GridGain, nodes: 3, status: active, cmgNodes: [node1, node2, node3], msNodes: [node1, node2, node3]]This means that all 3 nodes found each other and formed an active cluster. 
- 
Exit the CLI by typing exitor pressing Ctrl+D. This will also stop the CLI container.
Congratulations! You have a local GridGain 9 cluster running that you can use for development.
Understanding Port Configuration
The Docker Compose file exposes two types of ports for each node:
- 
10300-10302: REST API ports for administrative operations; 
- 
10800-10802: Client connection ports for your applications. 
Configuring Logs
Default Setup
By default, GridGain logs are written to the Docker container’s runtime output, meaning they are tied to the container’s lifecycle. These logs are not persistent as they are managed by the Docker and will be lost if the container is removed.
Use the docker logs command to access the logs:
docker logs <container-id>Custom Setup
To make logs persistent and redirect them to a file on the host system, follow these steps:
- 
Use the preconfigured file or create a new one and place it on the host system. Set a file path for the log output inside the container: handlers=java.util.logging.FileHandler java.util.logging.FileHandler.pattern=/gridgain/log/gridgain.log java.util.logging.FileHandler.append=true java.util.logging.FileHandler.limit=10000000 java.util.logging.FileHandler.count=5Make sure that java.util.logging.FileHandler.patternspecifies the full file path for the log file inside the container. It should match the mounted volume path (/gridgain/log) defined in step 2.
- 
Run the container with volume mounts to bind the log output directory and the config file to the host system: docker run \ -v /host/logs:/gridgain/log \ -v /host/logging.properties:/gridgain/config/logging.properties \ -e JAVA_OPTS="-Djava.util.logging.config.file=/gridgain/config/logging.properties" \ gridgain/image
- 
After the container starts, verify that the log file is created on the host: /host/logs/gridgain.log
Stopping the Cluster
If you want to pause your cluster:
docker compose stop
[+] Stopping 3/3
 ✔ Container gridgain9-node1-1  Stopped
 ✔ Container gridgain9-node3-1  Stopped
 ✔ Container gridgain9-node2-1  StoppedThis will stop the containers and retain your data.
Removing the Cluster
When you are done working with the cluster, you can remove it using:
docker compose down
[+] Running 4/4
 ✔ Container gridgain9-node3-1  Removed
 ✔ Container gridgain9-node1-1  Removed
 ✔ Container gridgain9-node2-1  Removed
 ✔ Network gridgain9_default    RemovedThis will stop and remove all the containers. Your data will be lost unless you have configured persistent storage.
© 2025 GridGain Systems, Inc. All Rights Reserved. Privacy Policy | Legal Notices. GridGain® is a registered trademark of GridGain Systems, Inc.
    Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.