Deploy Developer Edition with Docker Compose¶

Start NebulaGraph Database Developer Edition and NebulaGraph Studio on one development machine with Docker Compose. Once the services are running, you can connect and query sample data in your browser.

Before you start¶

A Windows, macOS, or Linux development machine with an AMD64 (x86_64) or ARM64 processor.
Docker and Docker Compose installed, with Docker running.
Access to the image registry and enough memory and disk space for Docker, NebulaGraph Database Developer Edition, and sample data.

Run the commands on this page in the terminal on the machine running Docker. On Windows, you can use PowerShell. First, check Docker:

docker compose version
docker info

Continue once you can see the Compose version and Docker service information. Resolve any missing command, connection, or permission errors first.

1. Create the deployment directory and download compose.yaml¶

Run these commands on your development machine to create and enter the deployment directory, dev-quickstart, and download compose.yaml. Database files and logs will also be stored here.

Linux / macOSWindows PowerShell

mkdir dev-quickstart
cd dev-quickstart
curl -fL -o compose.yaml \
  "https://dev-docs.nebula-graph.io/v5.3.2/get-started/files/compose.yaml"

New-Item -ItemType Directory -Path dev-quickstart
Set-Location dev-quickstart
Invoke-WebRequest -UseBasicParsing `
  -Uri "https://dev-docs.nebula-graph.io/v5.3.2/get-started/files/compose.yaml" `
  -OutFile compose.yaml

The file is saved as compose.yaml in the current directory. Run the remaining commands in this directory.

Alternatively, create an empty dev-quickstart directory, download compose.yaml in your browser, and save it there. Then open a terminal in that directory.

2. Set the login password¶

This page uses the NebulaGraph Database Developer Edition account root. The ROOT_PASSWORD setting in compose.yaml specifies its initial password:

ROOT_PASSWORD: 'NebulaGraph01'

You can keep this value. To change it, find this line in a text editor, replace the password inside the quotes, and save the file. Preserve the indentation and other settings.

Password requirements: At least eight characters, including an uppercase letter, a lowercase letter, and a digit. The password is set automatically on the first startup. Use it to sign in to NebulaGraph Studio later.

When reusing an existing data directory, enter the existing password and keep the default_svcgrp service group name. To change an existing instance's password, see Change an existing instance's root password.

Write a password that contains $

Write each $ as $$ in compose.yaml, and use a single $ when signing in. For example, an actual password of Graph$2026 is written as ROOT_PASSWORD: 'Graph$$2026'. This follows the Docker Compose escaping rules.

3. Start the services¶

Check the configuration in the deployment directory:
```
docker compose config --quiet
```
No output and no error means the check passed. If it fails, confirm that the terminal is in the deployment directory, the file is named compose.yaml, and the YAML indentation and quotes are correct.
Confirm that you accept the End User License Agreement (EULA), then start the services. The supplied compose.yaml sets ACCEPT_EULA: "Y" to indicate acceptance.
Linux / macOSWindows PowerShell
ACCEPT_EULA=Y docker compose up -d
docker compose up -d
For other startup commands on this page, omit ACCEPT_EULA=Y and keep the remaining arguments.
Missing images are pulled automatically. Once the command completes successfully, NebulaGraph Database Developer Edition and NebulaGraph Studio run in the background.

4. Check service status¶

In the same terminal, run:

docker compose ps --all

Check the STATUS column for all six services:

Service	Expected status
`metad`, `storaged`, `graphd`, ngql	`Up`
ngctl, `studio`	`Up` with `(healthy)`

The Graph and Storage services start after the ngctl health check passes. If services are still starting or health checks are pending, check again after a short wait. For Exited, repeated restarts, or unhealthy, see Troubleshoot deployment.

Common operations¶

Run these commands in your development machine's terminal, in the deployment directory.

Stop and restart the services

Stop the services:

docker compose stop

To use them again, start the existing containers:

docker compose start

stop keeps containers and data. Check service status, then follow Exit and resume your work to continue querying.

NebulaGraph Database Developer Edition data is stored in data/meta and data/storage under the deployment directory; logs are in logs. Keep the whole directory to reuse the data, and arrange backups separately.

Stop and start NebulaGraph Studio separately

With the NebulaGraph Database Developer Edition services running, you can manage NebulaGraph Studio separately:

Action	Command
Enable Studio after skipping it at startup	`docker compose up -d studio`
Stop Studio temporarily and keep its container	`docker compose stop studio`
Resume an existing, stopped Studio container	`docker compose start studio`

If you do not need the supplied Studio, use this command to start the services. If a Studio container already exists, the command removes it:

ACCEPT_EULA=Y docker compose up -d --scale studio=0

No studio container is created or kept; check the other five services. If you still do not need Studio, include --scale studio=0 in future up commands for the full deployment.

start studio only starts an existing container. After down, use up to recreate it. Removing the container preserves Studio's studio-data volume.

For login steps, see Connect and run your first query. For a separate installation, such as a binary package, see Install NebulaGraph Studio.

Change an existing instance's root password

Follow these steps only to change a running instance's password. Confirm that ngctl is healthy first. Editing ROOT_PASSWORD alone does not change an existing instance's password.

Replace <current-password> and <new-password> with the current and new passwords, then run:
```
docker compose exec ngctl ngctl auth passwd -H graph-cluster -P 9559 -u root -c '<current-password>' -p '<new-password>'
```
Enter the actual passwords without the Compose file's $$ escaping. If a password contains a single quote, escape it according to your terminal's rules. The new password must meet the password requirements. Continue only after the command reports Change password succeeded.
Update services.ngctl.environment.ROOT_PASSWORD in compose.yaml to the new password. Write each $ as $$ as described in Password escaping.
Check the configuration:
```
docker compose config --quiet
```
When validation passes, apply the update:
```
ACCEPT_EULA=Y docker compose up -d
```
If you do not need containerized Studio, use ACCEPT_EULA=Y docker compose up -d --scale studio=0 instead. docker compose restart does not apply the edited ROOT_PASSWORD environment variable.
Check service status, then sign in to ngql, the web console, or Studio again with the new password. Existing graph data is preserved; you do not need to reload the sample dataset.

Remove the services

docker compose down

This removes the deployment's containers and network, including studio if it was started, but keeps images, NebulaGraph Database Developer Edition's data and logs directories, and the NebulaGraph Studio studio-data volume.

Deleting data

docker compose down -v removes named volumes such as studio-data. Deleting the deployment directory also permanently deletes the NebulaGraph Database Developer Edition data. Before either action, confirm that you no longer need the data or have backed it up separately.

See Docker Compose configuration for service, port, and data directory settings, and Capabilities and limits for supported use and capacity limits.

Troubleshoot deployment¶

If services fail to start, view the logs in the deployment directory. If initialization has not finished, focus on the ngctl logs:

docker compose logs --tail 100
docker compose logs --tail 100 ngctl

Symptom	Action
Image pull fails	Check image names and tags against the supplied file, and check access to the registry
Container name is already in use	Run `docker ps -a` to find the container. Check its purpose before taking action to avoid deleting another instance
A port is already in use	Change the conflicting development machine port as described in Port configuration, then start again
Configuration is missing or YAML cannot be parsed	Check that the terminal is in the deployment directory, the file is named `compose.yaml`, and indentation and quotes are correct
`metad` logs show `EULA_NOT_ACCEPTED`	Once you accept the license agreement, set `services.metad.environment.ACCEPT_EULA` to the string `"Y"`, then start the services to recreate the container
`ngctl` keeps waiting to sign in	Check the password requirements. When reusing existing `data`, enter the existing password
`ngctl` health check fails and later services do not start	Inspect `ngctl` and `metad` logs; resolve sign-in or service group initialization errors first
Graph service or Storage service fails to start or keeps restarting	Check Docker's available memory. The supplied configuration requires 1 GiB to be reserved for the operating system and other processes. Keep the errors and the `data` directory to avoid losing existing data

After fixing the issue, start the services again.

Port mappings appear under metad

The Graph and Storage services share the Meta service's container network, so the 9559, 9779, 9669, and 19669 port mappings appear under metad. To change a development machine port, see Port configuration.

Studio page does not open¶

Check Studio's status and logs in the deployment directory:

docker compose ps --all studio

docker compose logs --tail 50 studio

Confirm that studio is running and that the browser address uses the development machine port in compose.yaml, which defaults to 7001. For remote access, also check that this port is reachable from the computer running the browser.

Next step¶

Once the services match the expected status, continue in NebulaGraph Studio to sign in, load sample data, and run queries:

Connect and run your first query →