Installation & Setup

Setting up Geode involves installing required dependencies, building from source, configuring the server, and establishing initial deployment parameters. This process transforms the source code into a running production-ready graph database capable of handling enterprise workloads with the 100% GQL compliance.

Prerequisites and Requirements Share link

Before beginning Geode installation, ensure your system meets minimum requirements and has necessary dependencies installed.

System Requirements Share link

Geode requires a modern Linux, macOS, or Windows environment with sufficient resources for development and production workloads:

• Operating System: Linux (Ubuntu 20.04+, Debian 11+, RHEL 8+), macOS 11+, or Windows 10/11 with WSL2
• CPU: 2+ cores (4+ recommended for production)
• Memory: 4GB minimum (8GB+ recommended for production)
• Storage: 10GB for binaries and source, plus data storage requirements
• Network: QUIC/UDP support (not blocked by firewall)

Build Dependencies Share link

Geode is written in Zig and requires specific build tools:

Zig Compiler: Version 0.1.0 or later is required for building Geode. Download from the official Zig website:

# Linux/macOS: Download and extract
wget https://ziglang.org/download/0.1.0/zig-linux-x86_64-0.1.0.tar.xz
tar -xf zig-linux-x86_64-0.1.0.tar.xz
sudo mv zig-linux-x86_64-0.1.0 /opt/zig
export PATH="/opt/zig:$PATH"

# Verify installation
zig version

Build Tools: Standard development tools may be needed:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install build-essential git make

# RHEL/CentOS
sudo yum groupinstall "Development Tools"
sudo yum install git make

# macOS (via Homebrew)
xcode-select --install
brew install git make

Network Configuration Share link

Geode uses QUIC over UDP on port 3141 by default. Ensure firewall rules allow this traffic:

# Ubuntu/Debian (ufw)
sudo ufw allow 3141/udp
sudo ufw reload

# RHEL/CentOS (firewalld)
sudo firewall-cmd --permanent --add-port=3141/udp
sudo firewall-cmd --reload

# Check port availability
netstat -an | grep 3141

Obtaining Geode Source Code Share link

Geode is distributed as source code through a Git repository.

Cloning the Repository Share link

Clone the complete monorepo containing the server and all client libraries:

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

# Or clone via SSH
git clone [email protected]:devnw/codepros/geode.git
cd geode

Repository Structure Share link

The monorepo contains multiple components:

geode/
├── geode/              # Main database server (Zig)
├── geode-client-go/    # Go client library
├── geode-client-python/  # Python client library
├── geode-client-rust/  # Rust client library
├── geode-client-zig/   # Zig client library
├── geode-test-harness/  # Cross-client test framework
└── gql/                # GQL reference implementation

Navigate to the server directory for database installation:

cd geode

Building Geode Share link

The build process compiles Geode from source, producing executable binaries.

Development Build Share link

Build a debug version for development and testing:

cd geode
make build

This creates debug binaries in zig-out/bin/ with full debugging symbols and safety checks enabled.

Production Build Share link

Build an optimized release version for production deployment:

make release

The release build enables optimizations while maintaining ReleaseSafe mode, which includes runtime safety checks. The resulting binary appears in zig-out/bin/geode.

Build Verification Share link

Verify the build completed successfully:

# Check binary exists
ls -lh zig-out/bin/geode

# Verify it runs
./zig-out/bin/geode --version

Build Options Share link

The Makefile supports several build targets:

# Clean build artifacts
make clean

# Run tests
make test

# Run comprehensive test suite (97.4% pass rate)
make geodetestlab-comprehensive

# Complete CI pipeline
make ci

Initial Configuration Share link

Configure Geode for your environment before first run.

Data Directory Share link

Geode stores data in a configured directory. Create this directory with appropriate permissions:

# Development setup
mkdir -p ./data

# Production setup
sudo mkdir -p /var/lib/geode/data
sudo chown geode:geode /var/lib/geode/data
sudo chmod 750 /var/lib/geode/data

TLS Certificates Share link

Geode requires TLS certificates for secure QUIC connections. For development, generate self-signed certificates:

# Generate self-signed certificate
openssl req -x509 -newkey rsa:4096 \
  -keyout key.pem -out cert.pem \
  -days 365 -nodes \
  -subj "/C=US/ST=State/L=City/O=Organization/CN=localhost"

# Set appropriate permissions
chmod 600 key.pem
chmod 644 cert.pem

For production, obtain certificates from a trusted Certificate Authority (Let’s Encrypt, etc.).

Environment Variables Share link

Configure environment variables for consistent operation:

# Add to ~/.bashrc or ~/.zshrc
export GEODE_DATA_DIR="/var/lib/geode/data"
export GEODE_CERT="/etc/geode/cert.pem"
export GEODE_KEY="/etc/geode/key.pem"
export GEODE_LOG_LEVEL="info"

Running Geode Share link

Start the Geode server with appropriate configuration.

Development Server Share link

Run a development server with default settings:

cd geode
./zig-out/bin/geode serve --listen 127.0.0.1:3141

The server starts and listens on localhost port 3141. Output indicates successful startup:

[INFO] Geode Graph Database v0.1.3
[INFO] Listening on 127.0.0.1:3141
[INFO] Data directory: ./data
[INFO] Ready for connections

Production Server Share link

Run with production-appropriate configuration:

./zig-out/bin/geode serve \
  --listen 0.0.0.0:3141 \
  --data-dir /var/lib/geode/data \
  --cert /etc/geode/cert.pem \
  --key /etc/geode/key.pem \
  --log-level info \
  --max-connections 1000

Server as System Service Share link

Configure Geode as a systemd service for automatic startup:

Create /etc/systemd/system/geode.service:

[Unit]
Description=Geode Graph Database
After=network.target
Documentation=https://geodedb.com

[Service]
Type=simple
User=geode
Group=geode
WorkingDirectory=/opt/geode
ExecStart=/opt/geode/zig-out/bin/geode serve \
  --listen 0.0.0.0:3141 \
  --data-dir /var/lib/geode/data \
  --cert /etc/geode/cert.pem \
  --key /etc/geode/key.pem \
  --log-level info
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=geode

# Security settings
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/geode
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable geode
sudo systemctl start geode
sudo systemctl status geode

Verifying Installation Share link

Confirm Geode is running correctly and accepting connections.

Connection Testing Share link

Use the Geode shell to test connectivity:

./zig-out/bin/geode shell

# At the prompt, test basic operations
> PING
PONG

> CREATE (n:Person {name: 'Alice', age: 30}) RETURN n;
> MATCH (n:Person) RETURN n;

Successful responses indicate proper installation.

Client Library Testing Share link

Test connectivity from client libraries:

// Go client test
package main

import (
    "context"
    "fmt"
    "log"
    "geodedb.com/geode"
)

func main() {
    client, err := geode.NewClient("localhost:3141")
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    ctx := context.Background()
    if err := client.Ping(ctx); err != nil {
        log.Fatal(err)
    }
    fmt.Println("Connected successfully!")
}

Performance Baseline Share link

Run baseline performance tests to establish expected performance:

cd geode
make test

This runs the test suite and provides performance metrics for comparison against future runs.

User and Access Setup Share link

Configure users and access controls for multi-user environments.

Creating Users Share link

While Geode’s authentication model depends on your deployment, establish basic access patterns:

-- Create user accounts (example, actual implementation may vary)
CREATE USER admin WITH PASSWORD 'secure_password';
CREATE USER app_user WITH PASSWORD 'app_password';

Access Policies Share link

Configure Row-Level Security policies for fine-grained access control:

-- Enable RLS on sensitive tables
ALTER TABLE Person ENABLE ROW LEVEL SECURITY;

-- Create access policies
CREATE POLICY user_access ON Person
FOR SELECT
USING (owner_id = current_user_id());

Client Setup Share link

Configure client libraries to connect to Geode.

Go Client Setup Share link

# Install Go client
go get geodedb.com/geode

# Import in your application
import "geodedb.com/geode"

Python Client Setup Share link

cd geode-client-python

# Install dependencies
pip install -r requirements.txt

# Install client
pip install -e .

Rust Client Setup Share link

cd geode-client-rust

# Build client
cargo build --release

# Add to Cargo.toml
[dependencies]
geode-client = { path = "../geode-client-rust" }

Zig Client Setup Share link

cd geode-client-zig

# Build client
zig build

# Run example
zig build run

Initial Data Loading Share link

Load initial data into your Geode instance.

Bulk Data Import Share link

For large datasets, use batch operations:

BEGIN TRANSACTION;

UNWIND $nodes AS node
CREATE (n:Person {
  id: node.id,
  name: node.name,
  email: node.email
});

UNWIND $relationships AS rel
MATCH (a:Person {id: rel.from})
MATCH (b:Person {id: rel.to})
CREATE (a)-[:KNOWS]->(b);

COMMIT;

Schema Initialization Share link

Create indexes and constraints:

-- Create indexes for performance
CREATE INDEX ON Person(email);
CREATE INDEX ON Person(name);
CREATE INDEX ON Company(name);

-- Create unique constraints
CREATE CONSTRAINT ON Person(email) ASSERT email IS UNIQUE;

Troubleshooting Setup Issues Share link

Common setup problems and solutions.

Build Failures Share link

If build fails, verify Zig version and dependencies:

zig version  # Should be 0.1.0+
make clean
make build

Connection Refused Share link

If clients cannot connect, check server is running and firewall allows traffic:

# Verify server running
ps aux | grep geode

# Check port listening
netstat -an | grep 3141

# Test locally
./zig-out/bin/geode shell

Permission Errors Share link

Ensure data directory has correct permissions:

sudo chown -R geode:geode /var/lib/geode
sudo chmod -R 750 /var/lib/geode

Certificate Issues Share link

For TLS certificate problems, verify certificate files are readable:

ls -l cert.pem key.pem
openssl x509 -in cert.pem -text -noout

Post-Installation Steps Share link

Complete setup with operational configuration.

Backup Configuration Share link

Establish backup procedures:

# Create backup script
cat > /opt/geode/backup.sh <<'EOF'
#!/bin/bash
BACKUP_DIR="/backup/geode/$(date +%Y%m%d)"
mkdir -p $BACKUP_DIR
rsync -av /var/lib/geode/data/ $BACKUP_DIR/
EOF

chmod +x /opt/geode/backup.sh

# Schedule daily backups
crontab -e
# Add: 0 2 * * * /opt/geode/backup.sh

Monitoring Setup Share link

Configure monitoring for production systems:

# Enable slow query logging
./zig-out/bin/geode serve \
  --slow-query-log \
  --slow-query-threshold 1000

Documentation Review Share link

Review relevant documentation:

• Geode server configuration reference
• Client library documentation for your language
• GQL query language syntax
• Performance tuning guides

Related Topics Share link

Setup connects to several operational areas:

• Installation - Detailed installation procedures
• Configuration - Advanced configuration options
• Deployment - Production deployment strategies
• Operations - Ongoing operational management
• Troubleshooting - Resolving setup and operational issues

Resources Share link

Additional setup resources:

• Official Geode documentation at geodedb.com
• Build system documentation in geode/CLAUDE.md
• Client library setup guides in respective directories
• Community support and issue tracking

Proper installation and setup establishes the foundation for reliable Geode operation. Following these procedures ensures a stable, performant graph database ready for development and production workloads.