Docker deployment

Wiki / Operations

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

• ianknowles/galactus-db
• ianknowles/galactus-db-explorer

The examples use the latest image tag by default. This tag tracks the newest published preview. Set GALACTUS_DB_IMAGE and GALACTUS_EXPLORER_IMAGE to use a different release tag or digest.

Spatial release: 20 September 2026

The database image ianknowles/galactus-db:spatial-2026-09-20-b21201a adds spatial shapes, predicates, overlays, centroids and shape indexes for both AMD64 and ARM64. To pin this release, add this to .env:

GALACTUS_DB_IMAGE=ianknowles/galactus-db:spatial-2026-09-20-b21201a

Its multi-architecture manifest digest is sha256:60336b56551bb8715dab71d3f16f0589005545fbd98a522493490a6d61a32f52. Take a backup before upgrading: spatial snapshots and new commit segments use storage versions that older binaries cannot read. Restore a pre-upgrade backup if you need to return to an older binary.

Supported architectures

Both images target 64-bit Linux containers:

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}
    cpus: 2
    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_LICENSE_MODE: developer
      GDB_DURABILITY: group
    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.

Container defaults

The example explicitly selects the free Developer edition, two CPUs and group durability. These settings can be changed in compose.yaml.

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 termination; the services do not provide native TLS. See authentication.

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_LICENSE_MODE=developer --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.

Related articles

Configuration · Licensing · Backups