# Docker deployment

[Wiki](../README.md) / [Operations](README.md)

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

- [ianknowles/galactus-db](https://hub.docker.com/r/ianknowles/galactus-db)
- [ianknowles/galactus-db-explorer](https://hub.docker.com/r/ianknowles/galactus-db-explorer)

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`:

```dotenv
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.

```yaml
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:

```dotenv
GDB_INITIAL_PASSWORD=replace-with-your-password
```

Then start and inspect the stack:

```sh
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](../integrations/mcp.md). 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.

```yaml
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](authentication.md).

## 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](authentication.md#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:

```sh
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:

```sh
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.

## Related articles

[Configuration](configuration.md) · [Licensing](licensing.md) · [Backups](backups.md)
