Skip to content

Deploy Nebula Graph with Docker Compose

Using Docker Compose can quickly deploy Nebula Graph services based on the prepared configuration file. It is only recommended to use this method when testing functions of Nebula Graph.


  • If you are deploying Nebula Graph as a non-root user, grant the user with Docker-related privileges. For detailed instructions, see Manage Docker as a non-root user.
  • You have started the Docker service on your host.
  • If you have already deployed another version of Nebula Graph with Docker Compose on your host, to avoid compatibility issues, you need to delete the nebula-docker-compose/data directory.

How to deploy and connect to Nebula Graph

  1. Clone the 3.1.0 branch of the nebula-docker-compose repository to your host with Git.


    The master branch contains the untested code for the latest Nebula Graph development release. DO NOT use this release in a production environment.

    $ git clone -b release-3.1


    The x.y version of Docker Compose aligns to the x.y version of Nebula Graph. For the Nebula Graph z version, Docker Compose does not publish the corresponding z version, but pulls the z version of the Nebula Graph image.

  2. Go to the nebula-docker-compose directory.

    $ cd nebula-docker-compose/
  3. Run the following command to start all the Nebula Graph services.

    Starting with 3.0.2, Nebula Graph comes with ARM64 Linux Docker images. You can run containerized Nebula Graph databases on Docker Desktop for ARM macOS or on ARM Linux servers.


    Update the Nebula Graph images and Nebula Console images first if they are out of date.

    [nebula-docker-compose]$ docker-compose up -d
    Creating nebula-docker-compose_metad0_1 ... done
    Creating nebula-docker-compose_metad2_1 ... done
    Creating nebula-docker-compose_metad1_1 ... done
    Creating nebula-docker-compose_graphd2_1   ... done
    Creating nebula-docker-compose_graphd_1    ... done
    Creating nebula-docker-compose_graphd1_1   ... done
    Creating nebula-docker-compose_storaged0_1 ... done
    Creating nebula-docker-compose_storaged2_1 ... done
    Creating nebula-docker-compose_storaged1_1 ... done


    For more information of the preceding services, see Nebula Graph architecture.

  4. Connect to Nebula Graph.


    Starting from Nebula Graph version 3.1.0, nebula-docker-compose automatically starts a Nebula Console docker container and adds the storage host to the cluster (i.e. ADD HOSTS command).

    1. Run the following command to view the name of Nebula Console docker container.

      $ docker-compose ps
                Name                         Command             State                 Ports
      nebuladockercompose_console_1     sh -c sleep 3 &&          Up
                                        nebula-co ...
    2. Run the following command to enter the Nebula Console docker container.

      bash docker exec -it nebuladockercompose_console_1 /bin/sh / #

    3. Connect to Nebula Graph with Nebula Console.

      / # ./usr/local/bin/nebula-console -u <user_name> -p <password> --address=graphd --port=9669


      By default, the authentication is off, you can only log in with an existing username (the default is root) and any password. To turn it on, see Enable authentication.

    4. Run the following commands to view the cluster state.

      nebula> SHOW HOSTS;
      | Host        | Port | HTTP port | Status   | Leader count | Leader distribution  | Partition distribution | Version |
      | "storaged0" | 9779 | 19669     | "ONLINE" | 0            | "No valid partition" | "No valid partition"   | "3.1.0" |
      | "storaged1" | 9779 | 19669     | "ONLINE" | 0            | "No valid partition" | "No valid partition"   | "3.1.0" |
      | "storaged2" | 9779 | 19669     | "ONLINE" | 0            | "No valid partition" | "No valid partition"   | "3.1.0" |
  5. Run exit twice to switch back to your terminal (shell).

Check the Nebula Graph service status and ports

Run docker-compose ps to list all the services of Nebula Graph and their status and ports.

$ docker-compose ps
nebuladockercompose_console_1     sh -c sleep 3 &&                 Up
                                  nebula-co ...
nebuladockercompose_graphd1_1     /usr/local/nebula/bin/nebu ...   Up>19669/tcp,:::49174->19669/tcp,>19670/tcp,:::49171->19670/tcp,>9669/tcp,:::49177->9669/tcp
nebuladockercompose_graphd2_1     /usr/local/nebula/bin/nebu ...   Up>19669/tcp,:::49175->19669/tcp,>19670/tcp,:::49172->19670/tcp,>9669/tcp,:::49178->9669/tcp
nebuladockercompose_graphd_1      /usr/local/nebula/bin/nebu ...   Up>19669/tcp,:::49180->19669/tcp,>19670/tcp,:::49179->19670/tcp,>9669/tcp,:::9669->9669/tcp
nebuladockercompose_metad0_1      /usr/local/nebula/bin/nebu ...   Up>19559/tcp,:::49157->19559/tcp,>19560/tcp,:::49154->19560/tcp,>9559/tcp,:::49160->9559/tcp, 9560/tcp
nebuladockercompose_metad1_1      /usr/local/nebula/bin/nebu ...   Up>19559/tcp,:::49156->19559/tcp,>19560/tcp,:::49153->19560/tcp,>9559/tcp,:::49159->9559/tcp, 9560/tcp
nebuladockercompose_metad2_1      /usr/local/nebula/bin/nebu ...   Up>19559/tcp,:::49158->19559/tcp,>19560/tcp,:::49155->19560/tcp,>9559/tcp,:::49161->9559/tcp, 9560/tcp
nebuladockercompose_storaged0_1   /usr/local/nebula/bin/nebu ...   Up>19779/tcp,:::49166->19779/tcp,>19780/tcp,:::49163->19780/tcp, 9777/tcp, 9778/tcp,>9779/tcp,:::49169->9779/tcp, 9780/tcp
nebuladockercompose_storaged1_1   /usr/local/nebula/bin/nebu ...   Up>19779/tcp,:::49165->19779/tcp,>19780/tcp,:::49162->19780/tcp, 9777/tcp, 9778/tcp,>9779/tcp,:::49168->9779/tcp, 9780/tcp
nebuladockercompose_storaged2_1   /usr/local/nebula/bin/nebu ...   Up>19779/tcp,:::49167->19779/tcp,>19780/tcp,:::49164->19780/tcp, 9777/tcp, 9778/tcp,>9779/tcp,:::49170->9779/tcp, 9780/tcp

Nebula Graph provides services to the clients through port 9669 by default. To use other ports, modify the docker-compose.yaml file in the nebula-docker-compose directory and restart the Nebula Graph services.

Check the service data and logs

All the data and logs of Nebula Graph are stored persistently in the nebula-docker-compose/data and nebula-docker-compose/logs directories.

The structure of the directories is as follows:

  |-- docker-compose.yaml
  ├── data
  │   ├── meta0
  │   ├── meta1
  │   ├── meta2
  │   ├── storage0
  │   ├── storage1
  │   └── storage2
  └── logs
      ├── graph
      ├── graph1
      ├── graph2
      ├── meta0
      ├── meta1
      ├── meta2
      ├── storage0
      ├── storage1
      └── storage2

Stop the Nebula Graph services

You can run the following command to stop the Nebula Graph services:

$ docker-compose down

The following information indicates you have successfully stopped the Nebula Graph services:

Stopping nebuladockercompose_console_1   ... done
Stopping nebuladockercompose_graphd1_1   ... done
Stopping nebuladockercompose_graphd_1    ... done
Stopping nebuladockercompose_graphd2_1   ... done
Stopping nebuladockercompose_storaged1_1 ... done
Stopping nebuladockercompose_storaged0_1 ... done
Stopping nebuladockercompose_storaged2_1 ... done
Stopping nebuladockercompose_metad2_1    ... done
Stopping nebuladockercompose_metad0_1    ... done
Stopping nebuladockercompose_metad1_1    ... done
Removing nebuladockercompose_console_1   ... done
Removing nebuladockercompose_graphd1_1   ... done
Removing nebuladockercompose_graphd_1    ... done
Removing nebuladockercompose_graphd2_1   ... done
Removing nebuladockercompose_storaged1_1 ... done
Removing nebuladockercompose_storaged0_1 ... done
Removing nebuladockercompose_storaged2_1 ... done
Removing nebuladockercompose_metad2_1    ... done
Removing nebuladockercompose_metad0_1    ... done
Removing nebuladockercompose_metad1_1    ... done
Removing network nebuladockercompose_nebula-net


The parameter -v in the command docker-compose down -v will delete all your local Nebula Graph storage data. Try this command if you are using the nightly release and having some compatibility issues.

Modify configurations

The configuration file of Nebula Graph deployed by Docker Compose is nebula-docker-compose/docker-compose.yaml. To make the new configuration take effect, modify the configuration in this file and restart the service.

For more instructions, see Configurations.


How to fix the docker mapping to external ports?

To set the ports of corresponding services as fixed mapping, modify the docker-compose.yaml in the nebula-docker-compose directory. For example:

    image: vesoft/nebula-graphd:release-3.1
      - 9669:9669
      - 19669
      - 19670

9669:9669 indicates the internal port 9669 is uniformly mapped to external ports, while 19669 indicates the internal port 19669 is randomly mapped to external ports.

How to upgrade or update the docker images of Nebula Graph services

  1. In the nebula-docker-compose/docker-compose.yaml file, change all the image values to the required image version.

  2. In the nebula-docker-compose directory, run docker-compose pull to update the images of the Graph Service, Storage Service, Meta Service, and Nebula Console.

  3. Run docker-compose up -d to start the Nebula Graph services again.

  4. After connecting to Nebula Graph with Nebula Console, run SHOW HOSTS GRAPH, SHOW HOSTS STORAGE, or SHOW HOSTS META to check the version of the responding service respectively.

ERROR: toomanyrequests when docker-compose pull

You may meet the following error.

ERROR: toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading:

You have met the rate limit of Docker Hub. Learn more on Understanding Docker Hub Rate Limiting.

How to update the Nebula Console client

The command docker-compose pull updates both the Nebula Graph services and the Nebula Console.

Last update: May 12, 2022