Installation and Quick Start

Get Geode running locally in minutes, from zero to executing your first GQL query.

Prerequisites

System Requirements

Minimum:

  • CPU: 2 cores
  • RAM: 4GB
  • Disk: 2GB free space

Recommended:

  • CPU: 4+ cores
  • RAM: 8GB+
  • Disk: 10GB+ free space (SSD preferred)

Supported Platforms

  • Linux: Ubuntu 20.04+, Debian 11+, RHEL 8+, Arch Linux
  • macOS: macOS 11+ (Big Sur or later), including Apple Silicon
  • Windows: Windows 10+ with WSL2

Installation Options

Option 1: Install by Operating System 

# Add GPG signing key
curl -fsSL https://apt.geodedb.com/geode.gpg | \
  sudo gpg --dearmor -o /usr/share/keyrings/geode-archive-keyring.gpg

# Add repository
echo "deb [signed-by=/usr/share/keyrings/geode-archive-keyring.gpg] https://apt.geodedb.com stable main" | \
  sudo tee /etc/apt/sources.list.d/geode.list

# Install
sudo apt update
sudo apt install geode

curl -L -o geode.rpm https://gitlab.com/devnw/codepros/geode/geode/-/releases/latest/download/geode-linux-x86_64.rpm
sudo rpm -i geode.rpm

curl -L -o geode-linux-amd64 https://gitlab.com/devnw/codepros/geode/geode/-/releases/latest/download/geode-linux-amd64
chmod +x geode-linux-amd64
sudo install -m 0755 geode-linux-amd64 /usr/local/bin/geode

# Install via Homebrew (recommended)
brew install geodedb/geode/geode

# PowerShell
wsl --install -d Ubuntu

# Inside Ubuntu (WSL)
# Add GPG signing key
curl -fsSL https://apt.geodedb.com/geode.gpg | \
  sudo gpg --dearmor -o /usr/share/keyrings/geode-archive-keyring.gpg

# Add repository
echo "deb [signed-by=/usr/share/keyrings/geode-archive-keyring.gpg] https://apt.geodedb.com stable main" | \
  sudo tee /etc/apt/sources.list.d/geode.list

# Install
sudo apt update
sudo apt install geode

Option 2: Docker

Quick start with Docker Compose:

cd geode

# Single-node deployment
make docker-up-singleton

# Or distributed cluster
make docker-up-distributed

Manual Docker run:

# Pull image (when available)
docker pull geodedb/geode:latest

# Run server
docker run -d \
  -p 3141:3141 \
  -v geode-data:/var/lib/geode \
  --name geode \
  geodedb/geode:latest serve --listen 0.0.0.0:3141

Environment variables for Docker:

  • LOG_LEVEL: Set logging level (debug/info/warn/error)
  • GEODE_DATA_DIR: Data directory path (default: /var/lib/geode)
  • GEODE_ADMIN_USERNAME: Initial admin username
  • GEODE_DEFAULT_PASSWORD: Initial admin password

See Docker Deployment for the full production stack (Vault, MinIO, Prometheus, Grafana, Loki, Nginx).

Option 3: Build from Source

Requirements: Zig 0.1.0+ (download from ziglang.org )

# Clone repository
git clone https://github.com/codeprosorg/geode
cd geode

# Debug build (faster compilation)
make build

# Or release build (optimized, recommended for production)
make release

# Verify installation
geode --version

Make targets (from QUICK_REFERENCE.md):

  • make build - Debug build with symbols
  • make release - ReleaseSafe build (recommended)
  • make test - Run core unit tests
  • make geodetestlab-comprehensive - Full test suite (97.4% pass rate)

For detailed build options, see Install from Source .

Start the Server

Default Server Start 

# Start with defaults (QUIC/TLS on port 3141)
./geode serve

# Or if installed system-wide
geode serve

Default behavior:

  • Listens on 127.0.0.1:3141 (QUIC+TLS only, no TCP)
  • Data directory: ./geode-data (current directory)
  • Auto-generates self-signed certificates if none provided
  • Creates default admin user if GEODE_ADMIN_USERNAME / GEODE_DEFAULT_PASSWORD env vars are set

Custom Server Start 

# Custom listen address and data directory
./geode serve --listen 0.0.0.0:8443 --data-dir /var/lib/geode

# With TLS certificates (production)
./geode serve \
  --listen 0.0.0.0:3141 \
  --cert /etc/geode/certs/server-cert.pem \
  --key /etc/geode/certs/server-key.pem \
  --data-dir /var/lib/geode

# With configuration file
./geode serve --config /etc/geode/geode.yaml

Example configuration (geode.yaml from USAGE.md):

server:
  listen: '0.0.0.0:3141'
  data_dir: '/var/lib/geode'

tls:
  cert: '/etc/geode/certs/server-cert.pem'
  key: '/etc/geode/certs/server-key.pem'

storage:
  page_size: 8192
  page_cache_size: '1GB'

logging:
  level: 'info'
  format: 'json'

security:
  tde:
    enabled: true
    key_hex: '0123456789abcdef...'  # 32-byte hex key for AES-256-GCM

Connect and Run Your First Query

Using the Client CLI 

# Execute a single query
geode query "RETURN 1 AS x"

# Execute from file
geode query -f query.gql

# Choose output format
geode query --format json "MATCH (n) RETURN n LIMIT 10"
geode query --format txt "MATCH (n) RETURN n LIMIT 10"

Output formats (from USAGE.md):

  • txt - Human-readable table format (default)
  • json - JSON lines (one object per row)

Using the Interactive Shell

Start the REPL:

# Start interactive shell
./geode shell

# Or the alternative entrypoint
./gql

Key meta commands (from REPL_USAGE.md):

CommandDescription
\connect <uri>Connect to a server
\beginStart transaction
\commitCommit transaction
\rollbackRollback transaction
\format json|txtSet output format
\timing on|offShow query execution time
\helpShow help
\quitExit shell

Example session:

-- Connect to server
\connect quic://localhost:3141

-- Create a graph
CREATE GRAPH SocialNetwork;
USE SocialNetwork;

-- Create nodes
CREATE (:Person {name: "Alice", age: 30});
CREATE (:Person {name: "Bob", age: 25});

-- Create relationship
MATCH (a:Person {name: "Alice"}), (b:Person {name: "Bob"})
CREATE (a)-[:KNOWS {since: 2020}]->(b);

-- Query
MATCH (p:Person)-[k:KNOWS]->(friend)
RETURN p.name, friend.name, k.since;

-- Enable timing
\timing on

-- Run EXPLAIN
EXPLAIN MATCH (p:Person) RETURN p.name;

-- Start transaction
\begin

-- Make changes
CREATE (:Person {name: "Charlie", age: 35});

-- Commit
\commit

Troubleshooting

TLS/Certificate Issues

Symptom: “certificate verification failed” or “TLS handshake failed”

Solution:

# Verify certificate
openssl x509 -in /etc/geode/certs/server-cert.pem -text -noout

# Check certificate matches key
openssl x509 -noout -modulus -in server-cert.pem | openssl md5
openssl rsa -noout -modulus -in server-key.pem | openssl md5
# Should match

# For development, use self-signed cert
./geode serve  # Auto-generates if none present

Port Binding Issues

Symptom: “address already in use” or “bind failed”

Solution:

# Find process using port
lsof -i :3141

# Kill process
kill -9 <PID>

# Or use different port
./geode serve --listen 0.0.0.0:3142

Connection Issues

Symptom: “connection refused” or “cannot connect”

Checklist:

  1. Server running?

    ps aux | grep geode

  2. Correct port?

    # Check server logs for listening address

  3. Firewall blocking?

    # Check firewall rules
sudo ufw status  # Ubuntu/Debian
sudo firewall-cmd --list-all  # RHEL/CentOS

  4. QUIC support?

    • Geode requires QUIC (UDP transport). Ensure UDP port 3141 is open, not just TCP.

Next Steps

Now that Geode is running:

Health and Monitoring

Once running, check server health:

# Health check endpoint
curl http://localhost:8080/health

# Readiness check
curl http://localhost:8080/ready

# Prometheus metrics
curl http://localhost:8080/metrics

See Monitoring and Telemetry for full observability setup.