Quickly deploy NebulaGraph using Docker¶

You can quickly get started with NebulaGraph by deploying NebulaGraph with Docker Desktop or Docker Compose.

Using Docker DesktopUsing Docker Compose

NebulaGraph is available as a Docker Extension that you can easily install and run on your Docker Desktop. You can quickly deploy NebulaGraph using Docker Desktop with just one click.

Install Docker Desktop
- Install Docker Desktop on Mac
- Install Docker Desktop on Windows
Caution

To install Docker Desktop, you need to install WSL 2 first.
In the left sidebar of Docker Desktop, click Extensions or Add Extensions.
On the Extensions Marketplace, search for NebulaGraph and click Install.

Click Update to update NebulaGraph to the latest version when a new version is available.
Click Open to navigate to the NebulaGraph extension page.
At the top of the page, click Studio in Browser to use NebulaGraph.

For more information about how to use NebulaGraph with Docker Desktop, see the following video:

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

Prerequisites¶

You have installed the following applications on your host.

Application Recommended version Official installation reference

Docker Latest Install Docker Engine

Docker Compose Latest Install Docker Compose

Git Latest Download Git

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.

For NebulaGraph Enterprise, you must have the license key loaded in LM.

Deploy NebulaGraph¶

Clone the 3.5.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.5 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.

Note

For installation of the NebulaGraph enterprise version, contact us.
Go to the nebula-docker-compose directory.
```
$ cd nebula-docker-compose/
```

Configure License Manager address.

Enterpriseonly

Skip this step if you are using the community version.

Edit the docker-compose.yml file.

$ cd nebula-docker-compose/
$ vim docker-compose.yml

Add the license_manager_url field under all services.metad{number}.command and set its value to the access address of LM.

...
services:
  metad0:
    command:
      - --license_manager_url=<LM_ADDR>:<LM_PORT> // <LM_ADDR> is the address of the LM service, and <LM_PORT> is the port of the LM service, which is 9119 by default.
  metad1:
    command:
      - --license_manager_url=<LM_ADDR>:<LM_PORT>
  ...

Save and exit.

Run the following command to start all the NebulaGraph services.

Note

Update the NebulaGraph images and NebulaGraph Console images first if they are out of date.
The return result after executing the command varies depending on the installation directory.

[nebula-docker-compose]$ docker-compose up -d
Creating nebuladockercompose_metad0_1 ... done
Creating nebuladockercompose_metad2_1 ... done
Creating nebuladockercompose_metad1_1 ... done
Creating nebuladockercompose_graphd2_1   ... done
Creating nebuladockercompose_graphd_1    ... done
Creating nebuladockercompose_graphd1_1   ... done
Creating nebuladockercompose_storaged0_1 ... done
Creating nebuladockercompose_storaged2_1 ... done
Creating nebuladockercompose_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.

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

$ docker-compose ps
          Name                         Command             State                 Ports
--------------------------------------------------------------------------------------------
nebuladockercompose_console_1     sh -c sleep 3 &&          Up
                                  nebula-co ...
......

Run the following command to enter the NebulaGraph Console docker container.
```
docker exec -it nebuladockercompose_console_1 /bin/sh
/ #
```
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.

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.5.0" |
| "storaged1" | 9779 | "ONLINE" | 0            | "No valid partition" | "No valid partition"   | "3.5.0" |
| "storaged2" | 9779 | "ONLINE" | 0            | "No valid partition" | "No valid partition"   | "3.5.0" |
+-------------+------+----------+--------------+----------------------+------------------------+---------+

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
nebuladockercompose_console_1     sh -c sleep 3 &&                 Up
                                  nebula-co ...
nebuladockercompose_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
nebuladockercompose_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
nebuladockercompose_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
nebuladockercompose_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
nebuladockercompose_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
nebuladockercompose_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
nebuladockercompose_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
nebuladockercompose_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
nebuladockercompose_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 nebuladockercompose_graphd2_1).

Then you can execute docker ps to view the corresponding CONTAINER ID (such as 2a6c56c405f5).

[nebula-docker-compose]$ docker ps
CONTAINER ID   IMAGE                               COMMAND                  CREATED          STATUS                    PORTS                                                                                                  NAMES
2a6c56c405f5   vesoft/nebula-graphd:nightly     "/usr/local/nebula/b…"   36 minutes ago   Up 36 minutes (healthy)   0.0.0.0:49230->9669/tcp, 0.0.0.0:49229->19669/tcp, 0.0.0.0:49228->19670/tcp                            nebuladockercompose_graphd2_1
7042e0a8e83d   vesoft/nebula-storaged:nightly   "./bin/nebula-storag…"   36 minutes ago   Up 36 minutes (healthy)   9777-9778/tcp, 9780/tcp, 0.0.0.0:49227->9779/tcp, 0.0.0.0:49226->19779/tcp, 0.0.0.0:49225->19780/tcp   nebuladockercompose_storaged2_1
18e3ea63ad65   vesoft/nebula-storaged:nightly   "./bin/nebula-storag…"   36 minutes ago   Up 36 minutes (healthy)   9777-9778/tcp, 9780/tcp, 0.0.0.0:49219->9779/tcp, 0.0.0.0:49218->19779/tcp, 0.0.0.0:49217->19780/tcp   nebuladockercompose_storaged0_1
4dcabfe8677a   vesoft/nebula-graphd:nightly     "/usr/local/nebula/b…"   36 minutes ago   Up 36 minutes (healthy)   0.0.0.0:49224->9669/tcp, 0.0.0.0:49223->19669/tcp, 0.0.0.0:49222->19670/tcp                            nebuladockercompose_graphd1_1
a74054c6ae25   vesoft/nebula-graphd:nightly     "/usr/local/nebula/b…"   36 minutes ago   Up 36 minutes (healthy)   0.0.0.0:9669->9669/tcp, 0.0.0.0:49221->19669/tcp, 0.0.0.0:49220->19670/tcp                             nebuladockercompose_graphd_1
880025a3858c   vesoft/nebula-storaged:nightly   "./bin/nebula-storag…"   36 minutes ago   Up 36 minutes (healthy)   9777-9778/tcp, 9780/tcp, 0.0.0.0:49216->9779/tcp, 0.0.0.0:49215->19779/tcp, 0.0.0.0:49214->19780/tcp   nebuladockercompose_storaged1_1
45736a32a23a   vesoft/nebula-metad:nightly      "./bin/nebula-metad …"   36 minutes ago   Up 36 minutes (healthy)   9560/tcp, 0.0.0.0:49213->9559/tcp, 0.0.0.0:49212->19559/tcp, 0.0.0.0:49211->19560/tcp                  nebuladockercompose_metad0_1
3b2c90eb073e   vesoft/nebula-metad:nightly      "./bin/nebula-metad …"   36 minutes ago   Up 36 minutes (healthy)   9560/tcp, 0.0.0.0:49207->9559/tcp, 0.0.0.0:49206->19559/tcp, 0.0.0.0:49205->19560/tcp                  nebuladockercompose_metad2_1
7bb31b7a5b3f   vesoft/nebula-metad:nightly      "./bin/nebula-metad …"   36 minutes ago   Up 36 minutes (healthy)   9560/tcp, 0.0.0.0:49210->9559/tcp, 0.0.0.0:49209->19559/tcp, 0.0.0.0:49208->19560/tcp                  nebuladockercompose_metad1_1

Use the CONTAINER ID to log in the container and troubleshoot.

nebula-docker-compose]$ docker exec -it 2a6c56c405f5 bash
[root@2a6c56c405f5 nebula]#

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

Stop the NebulaGraph services¶

You can run the following command to stop the NebulaGraph services:

$ docker-compose down

The following information indicates you have successfully stopped the NebulaGraph 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

Danger

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

Modify configurations¶

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

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.5
    ...
    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¶

In the nebula-docker-compose/docker-compose.yaml file, change all the image values to the required image version.
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.
Run docker-compose up -d to start the NebulaGraph services again.
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.

Last update: August 4, 2023

Application	Recommended version	Official installation reference
Docker	Latest	Install Docker Engine
Docker Compose	Latest	Install Docker Compose
Git	Latest	Download Git

Quickly deploy NebulaGraph using Docker¶

Prerequisites¶

Deploy NebulaGraph¶

Connect to NebulaGraph¶

Check the NebulaGraph service status and ports¶

Check the service data and logs¶

Stop the NebulaGraph services¶

Modify configurations¶

FAQ¶

How to fix the docker mapping to external ports?¶

How to upgrade or update the docker images of NebulaGraph services¶

ERROR: toomanyrequests when docker-compose pull¶

How to update the NebulaGraph Console client¶

`ERROR: toomanyrequests` when `docker-compose pull`¶