Docker deployment

Wiki / Operations

Pull the database and Explorer images from Docker Hub. Both run as separate services; you only need Docker with Compose.

The examples use the latest image tag by default. This tag tracks the newest release (currently 2.5.0). Set GALACTUS_DB_IMAGE and GALACTUS_EXPLORER_IMAGE to use a different release tag or digest.

Pinning a release

Every database release is also published under its version tag. To pin one, add it to .env:

GALACTUS_DB_IMAGE=ianknowles/galactus-db:2.5.0

Releases from 1.0.1 onwards open each other's data directories unless their release notes say otherwise. If you are upgrading from an image older than the 20 September 2026 spatial release, take a backup first: spatial snapshots and newer commit segments use storage versions that older binaries cannot read.

Supported architectures

Both images target 64-bit Linux containers:

ImageARM64 (aarch64)AMD64 (x86-64)
galactus-dbSupportedSupported
galactus-db-explorerSupportedSupported

The release tags contain both architectures, so Docker selects the matching image for your container host. ARM64 is the 64-bit ARM target; 32-bit ARM images are not provided. On macOS or Windows, use Linux containers.

Compose quickstart

Save the following as compose.yaml, or download it from the site's Start building page.

name: galactus-development
services:
  db:
    image: ${GALACTUS_DB_IMAGE:-ianknowles/galactus-db:latest}
    environment:
      GDB_BIND: 0.0.0.0:7687
      GDB_DATA: /data/gdb
      GDB_INITIAL_USER: gdb
      GDB_INITIAL_PASSWORD: ${GDB_INITIAL_PASSWORD:?Set GDB_INITIAL_PASSWORD in .env}
      GDB_INITIAL_DATABASE: galactus
      GDB_DURABILITY: group
      GDB_AUTO_UPGRADE: "true"
    ports:
      - "127.0.0.1:7687:7687"
    volumes:
      - graph-data:/data
    healthcheck:
      test: ["CMD", "/usr/local/bin/gdb-server", "--healthcheck"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
  explorer:
    image: ${GALACTUS_EXPLORER_IMAGE:-ianknowles/galactus-db-explorer:latest}
    environment:
      GDB_EXPLORER_LISTEN: 0.0.0.0:7474
      GDB_EXPLORER_DEFAULT_ENDPOINT: bolt://db:7687
      GDB_EXPLORER_DEFAULT_USER: gdb
    ports:
      - "127.0.0.1:7474:7474"
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
volumes:
  graph-data:

Create a .env file beside it. Choose a password of at least 12 characters:

GDB_INITIAL_PASSWORD=replace-with-your-password

Then start and inspect the stack:

docker compose up -d
docker compose ps
docker compose logs -f db

Open http://127.0.0.1:7474 and log in as gdb with your configured password. Explorer connects to bolt://db:7687 inside the network. A driver on your host uses bolt://127.0.0.1:7687. The initial database is galactus.

Compose with the MCP server

To let AI assistants and agents use the database too, run the same stack with the MCP server. Save the following as compose.yaml instead, or download compose-mcp.yaml from the site's Start building page. It adds one service, ianknowles/galactus-db-mcp, and keeps the same project name and data volume, so you can switch between the two files.

name: galactus-development
services:
  db:
    image: ${GALACTUS_DB_IMAGE:-ianknowles/galactus-db:latest}
    environment:
      GDB_BIND: 0.0.0.0:7687
      GDB_DATA: /data/gdb
      GDB_INITIAL_USER: gdb
      GDB_INITIAL_PASSWORD: ${GDB_INITIAL_PASSWORD:?Set GDB_INITIAL_PASSWORD in .env}
      GDB_INITIAL_DATABASE: galactus
      GDB_DURABILITY: group
      GDB_AUTO_UPGRADE: "true"
    ports:
      - "127.0.0.1:7687:7687"
    volumes:
      - graph-data:/data
    healthcheck:
      test: ["CMD", "/usr/local/bin/gdb-server", "--healthcheck"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
  explorer:
    image: ${GALACTUS_EXPLORER_IMAGE:-ianknowles/galactus-db-explorer:latest}
    environment:
      GDB_EXPLORER_LISTEN: 0.0.0.0:7474
      GDB_EXPLORER_DEFAULT_ENDPOINT: bolt://db:7687
      GDB_EXPLORER_DEFAULT_USER: gdb
    ports:
      - "127.0.0.1:7474:7474"
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
  mcp:
    image: ${GALACTUS_MCP_IMAGE:-ianknowles/galactus-db-mcp:latest}
    environment:
      GDB_MCP_TRANSPORT: http
      GDB_MCP_BIND: 0.0.0.0:7688
      GDB_URI: bolt://db:7687
    ports:
      - "127.0.0.1:7688:7688"
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
volumes:
  graph-data:

Use the same .env file and docker compose up -d. The MCP endpoint is http://127.0.0.1:7688/mcp. MCP clients sign in with a Galactus DB user and password over HTTP Basic authentication, and the tools each user sees follow their roles. Create a user with only the roles an agent needs rather than giving it gdb; see authentication.

Container defaults

The example runs the free Community edition on every core the machine has, with group durability. These settings can be changed in compose.yaml.

SettingServer image defaultThis Compose example
Administratorgdbgdb
PasswordRequired; at least 12 charactersRequired from .env
Home databasegalactusgalactus
Instance directory/data/gdb/data/gdb
Durabilitybufferedgroup
EditionCommunity; no key requiredCommunity; every core
Published Bolt endpointChosen by the operator127.0.0.1:7687
ExplorerSeparate image127.0.0.1:7474

Keep GDB_BIND=0.0.0.0:7687 inside the container so other services can connect. Change the host side of the port mapping to choose an external address or port. For shared deployments, configure private networking and TLS: mount a certificate and set GDB_TLS_CERT / GDB_TLS_KEY for the database, and terminate TLS in front of Explorer. See encrypted connections.

The release images run as UID/GID 10001 and contain no shell or package manager. Database passwords use Argon2id. Use a separate writable data volume for each instance. For additional container isolation, both services support read_only: true, cap_drop: [ALL] and security_opt: [no-new-privileges:true]; the database still requires its writable /data volume.

Data and lifecycle

The named volume mounts at /data. The database stores its files below /data/gdb, with a separate directory for each database. A new named volume inherits the image's data-directory ownership. Bind-mounted directories must be writable by UID/GID 10001.

docker compose down retains the volume. docker compose down -v deletes it. Only one running server may own a durable directory.

For an upgrade, take a backup, check the release's compatibility, and set the new image tag or digest in .env. When using a registry:

docker compose pull
docker compose up -d
docker compose ps

Keep the previous image reference and a verified backup for your recovery plan. Do not assume an older image can read files written by a newer release.

Server image alone

Set GDB_INITIAL_PASSWORD in your shell, then run:

docker run -d --name galactus-db --cpus 2 -p 127.0.0.1:7687:7687 --env GDB_INITIAL_PASSWORD --env GDB_DURABILITY=group -v galactus-data:/data ianknowles/galactus-db:latest

The server image's healthcheck probes the Bolt listener. Check authentication and run a query to verify application access.

Configuration · Licensing · Backups

Planning a deployment? Review compatibility and licence setup for your instance.