ianknowles/galactus-db repository overview

⁠Galactus DB

Galactus DB is a property-graph database for connected datasets, with Cypher queries, Bolt 4.4 and 5.0–5.4 connectivity, and native graph data science (GDS) and APOC functionality.

This image runs the database server. The optional Galactus DB Explorer⁠ image provides a browser-based query workbench.

• Image: ianknowles/galactus-db:latest or a release tag such as ianknowles/galactus-db:1.4.1
• Platforms: Linux AMD64 (x86-64) and ARM64 (aarch64)
• Database port: 7687 (Bolt TCP and Bolt over WebSocket; native TLS optional)
• Persistent volume: /data
• Default administrator: gdb
• Default database: galactus

Use Linux containers on Docker Desktop for Windows or macOS. The latest tag tracks the newest release; each release is also published under its version tag (from 1.0.1). Pin a version tag or an image digest for repeatable deployments.

⁠Quick start

Create a file named gdb.env with your own password of at least 12 characters:

GDB_INITIAL_PASSWORD=replace-with-your-own-long-password

Keep this file private and out of source control. Start the database:

docker run -d --name galactus-db --cpus 2 --env-file gdb.env -e GDB_LICENSE_MODE=developer -e GDB_DURABILITY=group -p 127.0.0.1:7687:7687 -v galactus-data:/data ianknowles/galactus-db:latest

Connect with a Bolt client that supports protocol version 4.4 or 5.0–5.4:

Run a first query:

RETURN 'Hello from Galactus DB' AS message;

View server logs with docker logs -f galactus-db. The built-in healthcheck checks listener reachability; a successful authenticated query verifies database access.

⁠Docker Compose with Explorer

For a database and browser workbench together, use this setup as an alternative to the standalone command above. Save it as compose.yaml:

services:
  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: 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 compose.yaml, using your own password:

GDB_INITIAL_PASSWORD=replace-with-your-own-long-password

Start the services:

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

Open http://127.0.0.1:7474⁠ and sign in as gdb with your configured password. Explorer connects to bolt://db:7687 within the Compose network. Select galactus as the database. Applications running on your host connect to bolt://127.0.0.1:7687.

⁠Configuration

Configure the server through environment variables. These are release image defaults; both examples above explicitly select group durability.

buffered durability can lose acknowledged changes since the last sync after a power or kernel failure. group and sync wait for a covering disk sync before acknowledging commits.

Keep GDB_BIND=0.0.0.0:7687 inside the container. Use the host port mapping to control access. The examples publish ports only on loopback.

For remote access, use private networking and TLS. Mount a certificate and set GDB_TLS_CERT and GDB_TLS_KEY (PEM, certificate chain leaf first). The server then terminates TLS itself on port 7687 (bolt+s://) and refuses plaintext unless GDB_TLS_REQUIRED=false. Without a certificate the listener is plaintext. Keep GDB_METRICS_BIND on a private interface: the metrics endpoint is unauthenticated.

⁠Persistent data and upgrades

Mount a volume at /data to retain database files when replacing a container. The image runs as UID/GID 10001:10001. New named volumes inherit the image's directory ownership; bind-mounted directories must be writable by that user. Use a separate data directory for each instance, with only one running server accessing it.

docker compose down retains the named volume. Adding -v deletes it and its database files.

Before upgrading, arrange a verified backup and check storage compatibility for the target release. Native backup and restore require Commercial entitlement. Set the desired image tag or digest in your Compose file, then run:

docker compose pull
docker compose up -d
docker compose ps

Keep the previous image reference and your recovery copy. An older image is not guaranteed to read data written by a newer release.

⁠Editions and licensing

Galactus DB is proprietary software. Use is subject to the applicable licence grant and terms.

A fresh instance starts in free Developer mode without a licence key, registration, or online activation. Both free editions support reads, writes, Cypher, GDS, and APOC. For Personal mode, set GDB_LICENSE_MODE=personal and limit the container to one CPU.

Personal runs one active user database plus system, and Developer runs three plus system; image tags before 1.3.0 limit Developer to one. GDB_INITIAL_DATABASE selects the home database. Commercial supports any number of active user databases.

Commercial deployments require a Commercial licence. A licence is issued for one instance ID and a number of allocated cores. Run CALL gdb.license(); to see this instance's ID, its allocated cores and its licence status, and supply them when you order. The ID is generated once and kept in the data directory, so keep the volume, or set GDB_INSTANCE_ID to fix it explicitly.

Supply the token through GDB_LICENSE or a mounted file selected by GDB_LICENSE_FILE, set GDB_LICENSE_MODE=commercial, and limit the container to the licensed cores (for example --cpus 4). Reads stay available if a licence is missing, expired or exceeded; writes are refused until it is fixed.

⁠Compatibility notes

Galactus DB implements its own Cypher, GDS, and APOC functionality. Support is a subset of the corresponding Neo4j interfaces; applications should verify the queries and procedures they use. Drivers must be able to negotiate Bolt 4.4 or 5.0–5.4. The official Neo4j Python driver refuses any server agent that does not begin Neo4j/; start the server with GDB_NEO4J_AGENT=true to use it.

The server operates as a single node, without replicated clustering or failover. From 1.4.0, with GDB_CHANGE_STREAMS=on, a database can publish a change stream, feed subscriptions and trigger queues, and keep read-only replica databases on the same instance. Write execution is exclusive. Graph topology and indexes remain in memory, so size container memory for the workload as well as the property cache.

The runtime image contains no shell or package manager. Use docker logs and Bolt clients for diagnostics.