Docker Compose configuration

This reference explains the services, ports, environment variables, and data directories in the compose.yaml supplied with NebulaGraph Database Developer Edition. For the first deployment, follow Deploy Developer Edition with Docker Compose. After editing the file, apply and verify the changes.

Configuration file

Download compose.yaml into your deployment directory. It defines services, image addresses and versions, the initial password, networking, and data locations.

Images

Each service's image field contains its full image address and version. For example:

services:
  metad:
    image: reg.vesoft-inc.com/vesoft/nebula-metad-dev:5.3.2
  studio:
    image: vesoft/nebula-studio:5.3.2

Use the image registries, names, and tags specified by image in the supplied file. Keep these values for the first deployment. Before changing images, check compatibility between the services and tools.

Container environment variables

The table below lists the environment variables and values set in compose.yaml. Docker Compose passes them from each service's environment field into its container:

Variable	Configured value	Purpose
ACCEPT_EULA	"Y"	Indicates acceptance of the End User License Agreement (EULA); checked by the Meta service at startup.
ROOT_PASSWORD	NebulaGraph01	Initial root password set by ngctl; use the existing password when reusing data.
SERVICE_GROUP	default_svcgrp	Service group initialized by ngctl; keep the original name with existing data.
META_HOST, META_PORT	graph-cluster, 9559	Address and port used by ngctl to connect to the Meta service.
SERVICE_HOST	graph-cluster	Hostname used by ngctl to register the Graph and Storage services.
TZ	UTC	Timezone for metad and ngctl; the file does not pass it to other containers.
STUDIO_GRAPHD_DEFAULT_HOST, STUDIO_GRAPHD_DEFAULT_PORT	graph-cluster, 9669	Default Graph service address and port on the NebulaGraph Studio login page.

Before the first deployment, set the initial password in services.ngctl.environment.ROOT_PASSWORD. Use at least eight characters with an uppercase letter, a lowercase letter, and a digit. See Set the root password for escaping rules. To change an existing password, follow Change the root password of an existing NebulaGraph Database Developer Edition instance.

Services and fields

Each entry under services defines a container service:

Service	Purpose
Meta service (metad)	Manages information about hosts, service groups, partition placement, and user identities.
Storage service (storaged)	Stores graph data and system information for the service group.
Graph service (graphd)	Accepts connections and executes GQL queries.
ngctl	Sets the initial password and initializes the service group.
ngql	Provides the interactive query client.
studio	Graphical interface; starts with NebulaGraph Database Developer Edition by default.

The supplied file uses these configuration fields:

Field	Use in this file
image	Container image.
pull_policy: missing	Pulls images missing locally; does not refresh an existing image with the same tag on every startup.
container_name	Container name.
environment	Environment variables passed into the container, such as the initialization password.
entrypoint	Startup entry point for tool containers.
command	NebulaGraph Database Developer Edition startup arguments or tool scripts.
volumes	Maps development machine directories or Docker volumes to container directories.
ports	Maps container ports to development machine ports.
networks, network_mode	Container networking.
depends_on, healthcheck	Startup dependencies and checks.
restart: unless-stopped	Container restart policy; manually stopped containers remain stopped.

See Docker Compose service configuration for field syntax. Use spaces for YAML indentation and preserve the nesting of fields.

NebulaGraph Database Developer Edition startup arguments

Under services in compose.yaml, the command lists for metad, storaged, and graphd set their startup arguments:

Argument	Configured value	Purpose
--meta_server_addrs	graph-cluster:9559	Address used by NebulaGraph Database Developer Edition services to reach the Meta service.
--host	graph-cluster	Hostname used by all three services; matches the network alias configured under metad.networks.
--port	metad: 9559; storaged: 9779; graphd: 9669	Service port inside the container network.
--data_path	metad: /data/meta; storaged: /data/storage	Data directory inside the container.
--memory_dynamic_reserved_gb	storaged, graphd: 1	Each of the Graph and Storage services excludes 1 GiB from available system memory when calculating its dynamic memory limit.
--redirect_stdout	metad: false	Keeps standard output and standard error from being redirected to files. View the container output with docker compose logs metad.

If you change a service's hostname or container port, update the connection and service registration settings in ngctl to match.

To change only the port used to connect from the development machine, edit the host port to the left of the colon in the ports mapping. See Connect from the development machine.

Network and connection addresses

Name	Meaning
default_svcgrp	NebulaGraph Database Developer Edition service group name
graph-cluster-dev	Network key in compose.yaml; the Docker network name usually includes the Compose project prefix
graph-cluster	Network alias of metad, used by other containers to reach NebulaGraph Database Developer Edition services

The Graph and Storage services use network_mode: service:metad to share the Meta service's container network. Port mappings are therefore configured under metad.

The initialization script registers a host named graph-cluster in the service group. Here, a host is a record in NebulaGraph Database Developer Edition; a Docker host is the physical or virtual machine running Docker.

Developer Edition allows only one registered host per service group. The Graph and Storage services register with the same hostname and their respective ports. Tool containers such as ngctl and ngql do not count toward the number of registered hosts.

The supplied ngql connects to the Graph service at graph-cluster:9669 inside the container network. NebulaGraph Studio starts by default and uses the same address on its login page. See Connect and run your first query.

Connect from the development machine

The supplied file maps these ports to the same port numbers on the development machine:

Development machine port	Container port	Purpose
9559	9559	Meta service
9779	9779	Storage service
9669	9669	Graph query service
19669	19669	Graph HTTP service and the built-in NebulaGraph Database Console
7001	7001	NebulaGraph Studio web interface

In "9669:9669", the value to the left of the colon is the development machine port and the value to the right is the container port. If a development machine port is already in use, change only the left value. To move the Graph HTTP service to port 19670 on the development machine, replace only the "19669:19669" line in metad's ports list with:

- "19670:19669"

The Graph HTTP port remains 19669 inside the container, while clients on the development machine use 19670. After changing the mapping, apply and verify the configuration.

With the default port mapping, a Graph client on the development machine, such as an SDK, can connect to 127.0.0.1:9669 using a NebulaGraph Database Developer Edition username and password. If you change the development machine port on the left side of 9669:9669, use that port instead. The built-in NebulaGraph Database Console uses the Graph HTTP port; see Connect and run your first query for its browser address and login steps.

The studio service defines 7001:7001 to map the NebulaGraph Studio web port to the development machine. See Connect and run your first query.

Data, log, and examples directories

For example, the Meta data directory is mapped as follows:

volumes:
  - ./data/meta:/data/meta

The left side is the development machine directory; the right side is the container directory. In the supplied configuration, ./ refers to the directory containing compose.yaml.

Development machine directory	Container directory	Contents
./data/meta	/data/meta	Meta data
./data/storage	/data/storage	Storage data, including graph data
./logs/meta	/usr/local/nebula/logs	Meta logs
./logs/storage	/usr/local/nebula/logs	Storage logs
./logs/graph	/usr/local/nebula/logs	Graph logs
./examples	/examples	Algorithm sample CSV files and exported results; mounted in graphd

Each log directory maps to /usr/local/nebula/logs in its own container. Logs remain separated by service on the development machine.

Save algorithm files under examples/algorithms/ on the development machine. GQL import and export statements use the /examples/algorithms/ container path. For downloads and save locations, see Prepare algorithm sample data.

The studio service stores its data in the studio-data Docker volume, outside the ./data directory.

Changing the left-hand directory changes where the container reads data; it does not migrate existing data. Keep the original mapping to continue using your data. See Stop and restart NebulaGraph Database Developer Edition for data retention when stopping or removing containers.

Apply and verify changes

Run all commands in the development machine's terminal, in the directory containing compose.yaml. Applying changes can recreate containers; do this when no queries are running. For PowerShell syntax, see Windows PowerShell.

1. Edit compose.yaml and save it. For an initial deployment, set the password and keep other supplied values.

2. Validate configuration syntax:

   docker compose config --quiet
   

   Successful completion with no output means configuration validation passed, not that NebulaGraph Database Developer Edition is available. Full configuration output can contain passwords; do not share it directly.

3. Apply the configuration:

   ACCEPT_EULA=Y docker compose up -d
   

   If you do not need containerized NebulaGraph Studio, use ACCEPT_EULA=Y docker compose up -d --scale studio=0 instead. Include this option each time you run up; see Docker Compose up for its meaning.

   docker compose restart does not apply edited container configuration or environment variables.

4. Inspect container status:

   docker compose ps --all
   

   Follow Check service status, then connect to NebulaGraph Database Developer Edition and run a query. If startup fails, see Deployment troubleshooting.