Docker deployment
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:
| Image | ARM64 (aarch64) | AMD64 (x86-64) |
|---|---|---|
galactus-db | Supported | Supported |
galactus-db-explorer | Supported | Supported |
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.
| Setting | Server image default | This Compose example |
|---|---|---|
| Administrator | gdb | gdb |
| Password | Required; at least 12 characters | Required from .env |
| Home database | galactus | galactus |
| Instance directory | /data/gdb | /data/gdb |
| Durability | buffered | group |
| Edition | Community; no key required | Community; every core |
| Published Bolt endpoint | Chosen by the operator | 127.0.0.1:7687 |
| Explorer | Separate image | 127.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.