Skip to content

Deploy NebulaGraph with Docker Compose

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

Prerequisites

  • If you are deploying NebulaGraph 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 NebulaGraph with Docker Compose on your host, to avoid compatibility issues, you need to delete the nebula-docker-compose/data directory.

Deploy NebulaGraph

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

    Danger

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

    $ git clone -b release-3.8 https://github.com/vesoft-inc/nebula-docker-compose.git

    Note

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

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

    $ cd nebula-docker-compose/

  3. Run the following command to start all the NebulaGraph services.

    Note

    [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

    Compatibility

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

    Note

    For more information of the preceding services, see NebulaGraph architecture.

Connect to NebulaGraph

There are two ways to connect to NebulaGraph:

  • Connected with Nebula Console outside the container. Because the external mapping port for the Graph service is also fixed as 9669 in the container's configuration file, you can connect directly through the default port. For details, see Connect to NebulaGraph.
  • Log into the container installed NebulaGraph Console, then connect to the Graph service. This section describes this approach.

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

    $ docker-compose ps
            Name                             Command                  State                                        Ports                                 
-----------------------------------------------------------------------------------------------------------------------------------------------------------
nebula-docker-compose_console_1     sh -c for i in `seq 1 60`; ...   Up                                                                                    
nebula-docker-compose_graphd1_1     /usr/local/nebula/bin/nebu ...   Up (healthy)   0.0.0.0:32847->15669/tcp,:::32847->15669/tcp, 19669/tcp,               
                                                                                    0.0.0.0:32846->19670/tcp,:::32846->19670/tcp,                          
                                                                                    0.0.0.0:32849->5669/tcp,:::32849->5669/tcp, 9669/tcp         
......

    Note

    nebula-docker-compose_console_1 and nebula-docker-compose_graphd1_1 are the container names of NebulaGraph Console and Graph Service respectively.

  2. Run the following command to enter the NebulaGraph Console docker container.

    docker exec -it nebula-docker-compose_console_1 /bin/sh
/ #

  3. Connect to NebulaGraph with NebulaGraph Console.

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

    Note

    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 | Status   | Leader count | Leader distribution  | Partition distribution | Version |
+-------------+------+----------+--------------+----------------------+------------------------+---------+
| "storaged0" | 9779 | "ONLINE" | 0            | "No valid partition" | "No valid partition"   | "3.8.0" |
| "storaged1" | 9779 | "ONLINE" | 0            | "No valid partition" | "No valid partition"   | "3.8.0" |
| "storaged2" | 9779 | "ONLINE" | 0            | "No valid partition" | "No valid partition"   | "3.8.0" |
+-------------+------+----------+--------------+----------------------+------------------------+---------+

  5. Use basic nGQL commands. For more information, see Use nGQL (CRUD).

Run exit twice to switch back to your terminal (shell).

Check the NebulaGraph service status and ports

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

Note

NebulaGraph 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 NebulaGraph services.

$ docker-compose ps
nebula-docker-compose_console_1     sh -c sleep 3 &&                 Up
                                  nebula-co ...
nebula-docker-compose_graphd1_1     /usr/local/nebula/bin/nebu ...   Up      0.0.0.0:49174->19669/tcp,:::49174->19669/tcp, 0.0.0.0:49171->19670/tcp,:::49171->19670/tcp, 0.0.0.0:49177->9669/tcp,:::49177->9669/tcp
nebula-docker-compose_graphd2_1     /usr/local/nebula/bin/nebu ...   Up      0.0.0.0:49175->19669/tcp,:::49175->19669/tcp, 0.0.0.0:49172->19670/tcp,:::49172->19670/tcp, 0.0.0.0:49178->9669/tcp,:::49178->9669/tcp
nebula-docker-compose_graphd_1      /usr/local/nebula/bin/nebu ...   Up      0.0.0.0:49180->19669/tcp,:::49180->19669/tcp, 0.0.0.0:49179->19670/tcp,:::49179->19670/tcp, 0.0.0.0:9669->9669/tcp,:::9669->9669/tcp
nebula-docker-compose_metad0_1      /usr/local/nebula/bin/nebu ...   Up      0.0.0.0:49157->19559/tcp,:::49157->19559/tcp, 0.0.0.0:49154->19560/tcp,:::49154->19560/tcp, 0.0.0.0:49160->9559/tcp,:::49160->9559/tcp, 9560/tcp
nebula-docker-compose_metad1_1      /usr/local/nebula/bin/nebu ...   Up      0.0.0.0:49156->19559/tcp,:::49156->19559/tcp, 0.0.0.0:49153->19560/tcp,:::49153->19560/tcp, 0.0.0.0:49159->9559/tcp,:::49159->9559/tcp, 9560/tcp
nebula-docker-compose_metad2_1      /usr/local/nebula/bin/nebu ...   Up      0.0.0.0:49158->19559/tcp,:::49158->19559/tcp, 0.0.0.0:49155->19560/tcp,:::49155->19560/tcp, 0.0.0.0:49161->9559/tcp,:::49161->9559/tcp, 9560/tcp
nebula-docker-compose_storaged0_1   /usr/local/nebula/bin/nebu ...   Up      0.0.0.0:49166->19779/tcp,:::49166->19779/tcp, 0.0.0.0:49163->19780/tcp,:::49163->19780/tcp, 9777/tcp, 9778/tcp, 0.0.0.0:49169->9779/tcp,:::49169->9779/tcp, 9780/tcp
nebula-docker-compose_storaged1_1   /usr/local/nebula/bin/nebu ...   Up      0.0.0.0:49165->19779/tcp,:::49165->19779/tcp, 0.0.0.0:49162->19780/tcp,:::49162->19780/tcp, 9777/tcp, 9778/tcp, 0.0.0.0:49168->9779/tcp,:::49168->9779/tcp, 9780/tcp
nebula-docker-compose_storaged2_1   /usr/local/nebula/bin/nebu ...   Up      0.0.0.0:49167->19779/tcp,:::49167->19779/tcp, 0.0.0.0:49164->19780/tcp,:::49164->19780/tcp, 9777/tcp, 9778/tcp, 0.0.0.0:49170->9779/tcp,:::49170->9779/tcp, 9780/tcp

If the service is abnormal, you can first confirm the abnormal container name (such as nebula-docker-compose_graphd2_1) and then log in to the container and troubleshoot.

$ docker exec -it nebula-docker-compose_graphd2_1 bash

Check the service data and logs

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

The structure of the directories is as follows:

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

Modify configurations

The configuration file of 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.

The configurations in the docker-compose.yaml file overwrite the configurations in the configuration file (/usr/local/nebula/etc) of the containered NebulaGraph service. Therefore, you can modify the configurations in the docker-compose.yaml file to customize the configurations of the NebulaGraph service.

For more instructions, see Configurations.

Restart NebulaGraph services

To restart all the NebulaGraph services, run the following command:

$ docker-compose restart
Restarting nebula-docker-compose_console_1   ... done
Restarting nebula-docker-compose_graphd_1    ... done
Restarting nebula-docker-compose_graphd1_1   ... done
Restarting nebula-docker-compose_graphd2_1   ... done
Restarting nebula-docker-compose_storaged1_1 ... done
Restarting nebula-docker-compose-storaged0_1 ... done
Restarting nebula-docker-compose_storaged2_1 ... done
Restarting nebula-docker-compose_metad1_1    ... done
Restarting nebula-docker-compose_metad2_1    ... done
Restarting nebula-docker-compose_metad0_1    ... done

To restart multiple services, such as graphd and storaged0, run the following command:

$ docker-compose restart graphd storaged0
Restarting nebula-docker-compose_graphd_1    ... done
Restarting nebula-docker-compose_storaged0_1 ... done

Stop and remove NebulaGraph services

You can stop and remove all the NebulaGraph services by running the following command:

Danger

This command stops and removes all the containers of the NebulaGraph services and the related network. If you define volumes in the docker-compose.yaml, the related data are retained.

The command docker-compose down -v removes all the local data. Try this command if you are using the nightly release and having some compatibility issues.

$ docker-compose down

The following information indicates you have successfully stopped the NebulaGraph services:

Stopping nebula-docker-compose_console_1   ... done
Stopping nebula-docker-compose_graphd1_1   ... done
Stopping nebula-docker-compose_graphd_1    ... done
Stopping nebula-docker-compose_graphd2_1   ... done
Stopping nebula-docker-compose_storaged1_1 ... done
Stopping nebula-docker-compose_storaged0_1 ... done
Stopping nebula-docker-compose_storaged2_1 ... done
Stopping nebula-docker-compose_metad2_1    ... done
Stopping nebula-docker-compose_metad0_1    ... done
Stopping nebula-docker-compose_metad1_1    ... done
Removing nebula-docker-compose_console_1   ... done
Removing nebula-docker-compose_graphd1_1   ... done
Removing nebula-docker-compose_graphd_1    ... done
Removing nebula-docker-compose_graphd2_1   ... done
Removing nebula-docker-compose_storaged1_1 ... done
Removing nebula-docker-compose_storaged0_1 ... done
Removing nebula-docker-compose_storaged2_1 ... done
Removing nebula-docker-compose_metad2_1    ... done
Removing nebula-docker-compose_metad0_1    ... done
Removing nebula-docker-compose_metad1_1    ... done
Removing network nebula-docker-compose_nebula-net

FAQ

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:

graphd:
    image: vesoft/nebula-graphd:release-3.8
    ...
    ports:
      - 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 NebulaGraph 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 NebulaGraph Console.

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

  4. After connecting to NebulaGraph with NebulaGraph 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: https://www.docker.com/increase-rate-limit.

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

How to update the NebulaGraph Console client?

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

How to activate storaged containers when they remain in offline status?

The activation script for storaged containers in Docker Compose may fail to run in rare cases. You can connect to NebulaGraph with NebulaGraph Console or NebulaGraph Studio and then manually run the ADD HOSTS command to activate them by adding the storaged containers to the cluster. An example of the command is as follows:

nebula> ADD HOSTS "storaged0":9779,"storaged1":9779,"storaged2":9779
Last update: May 30, 2025