Source: https://dev-docs.nebula-graph.io/v5.3.2/server-admin/configurations/docker-compose/ Documentation version: v5.3.2 # 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](https://dev-docs.nebula-graph.io/v5.3.2/get-started/deploy/). After editing the file, [apply and verify the changes](https://dev-docs.nebula-graph.io/v5.3.2/server-admin/configurations/docker-compose/#apply). ## Configuration file Download [compose.yaml](https://dev-docs.nebula-graph.io/v5.3.2/get-started/files/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](https://dev-docs.nebula-graph.io/v5.3.2/get-started/deploy/#root-password) for escaping rules. To change an existing password, follow [Change the root password of an existing NebulaGraph Database Developer Edition instance](https://dev-docs.nebula-graph.io/v5.3.2/get-started/deploy/#change-root-password). ## 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](https://docs.docker.com/reference/compose-file/services/) 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](https://dev-docs.nebula-graph.io/v5.3.2/server-admin/configurations/docker-compose/#ports). ## 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](https://dev-docs.nebula-graph.io/v5.3.2/get-started/first-query/#connect). ### 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](https://dev-docs.nebula-graph.io/v5.3.2/server-admin/configurations/docker-compose/#apply). 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](https://dev-docs.nebula-graph.io/v5.3.2/get-started/first-query/#web-console) 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](https://dev-docs.nebula-graph.io/v5.3.2/get-started/first-query/#connect). ## 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](https://dev-docs.nebula-graph.io/v5.3.2/analytic/algorithms/prepare-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](https://dev-docs.nebula-graph.io/v5.3.2/get-started/deploy/#stop-start) 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](https://dev-docs.nebula-graph.io/v5.3.2/get-started/deploy/#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](https://docs.docker.com/reference/cli/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](https://dev-docs.nebula-graph.io/v5.3.2/get-started/deploy/#check-services), then [connect to NebulaGraph Database Developer Edition](https://dev-docs.nebula-graph.io/v5.3.2/get-started/first-query/#connect) and run a query. If startup fails, see [Deployment troubleshooting](https://dev-docs.nebula-graph.io/v5.3.2/get-started/deploy/#troubleshooting).