Installation

Get Geode running on your system with step-by-step installation instructions for all supported platforms and installation methods.

Overview

Geode provides multiple installation options to suit different use cases and environments. Whether you’re installing OS packages, deploying with Docker for production, or building from source for development, Geode supports your workflow.

This section provides comprehensive installation guides for each method, including platform-specific instructions, prerequisites, verification steps, and troubleshooting tips.

Installation Methods

OS Packages and Binaries

Install Geode from official release artifacts. This method is ideal for:

  • Quick Start: Install without build tools
  • Platform Support: Linux .deb/.rpm packages and macOS binaries
  • Automation: Easy to roll out via configuration management
  • Stability: Versioned release artifacts

See: Quick Start or Getting Started

Build from Source

Build Geode from source code using the Zig compiler. This method gives you the most control and is ideal for:

  • Development: Contributing to Geode or customizing the database
  • Latest Features: Access to unreleased features in the main branch
  • Platform Support: Build for any platform supported by Zig
  • Optimization: Custom build flags for specific hardware

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

See: Build from Source

Docker Installation

Run Geode in Docker containers for isolated, reproducible deployments. Docker installation is ideal for:

  • Quick Start: Get running in minutes without installing dependencies
  • Production: Container orchestration with Docker Compose or Kubernetes
  • Isolation: Run multiple Geode instances on the same host
  • CI/CD: Consistent test environments

Requirements: Docker 20.10+ or Docker Desktop

See: Docker Deployment

Topics in This Section

  • From Source - Build Geode from source code with Zig including prerequisites, build commands, and platform-specific instructions

Platform Support

Linux

Distributions:

  • Ubuntu 20.04+ (LTS recommended)
  • Debian 11+ (Bullseye or later)
  • RHEL 8+ / CentOS Stream 8+
  • Fedora 35+
  • Arch Linux (rolling release)

Architectures: x86_64 (amd64), ARM64 (aarch64)

macOS

Versions: macOS 11+ (Big Sur or later)

Architectures: x86_64 (Intel), ARM64 (Apple Silicon)

Windows

Via WSL2: Windows 10+ with Windows Subsystem for Linux 2

Note: Native Windows support is planned but not yet available. Use WSL2 for now.

System Requirements

Minimum Requirements

  • CPU: 2 cores
  • RAM: 4GB
  • Disk: 2GB free space
  • Network: For distributed deployments, stable network connectivity
  • CPU: 4+ cores
  • RAM: 8GB+ (16GB for large datasets)
  • Disk: 10GB+ free space (SSD highly recommended)
  • Network: 1Gbps+ for distributed deployments

Production Requirements

  • CPU: 8+ cores (16+ for high-throughput workloads)
  • RAM: 32GB+ (proportional to dataset size and query complexity)
  • Disk: 100GB+ NVMe SSD (RAID 10 recommended)
  • Network: 10Gbps+ for distributed deployments with low latency

Quick Start

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

# Start the server
geode serve --listen 0.0.0.0:3141

Option 2: Docker (Fastest) 

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

# Verify server is running
docker logs geode

Option 3: Build from Source 

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

# Build (requires Zig 0.1.0+)
make build

# Start server
./zig-out/bin/geode serve

# Verify installation
./zig-out/bin/geode --version

Verification

After installation, verify Geode is working correctly:

# Check version
geode --version

# Start server
geode serve

# In another terminal, connect with shell
geode shell

# Run test query
RETURN 1 AS x;

Expected output:

┌───┐
│ x │
├───┤
│ 1 │
└───┘

Post-Installation

Configure TLS Certificates

For production deployments, configure TLS certificates instead of using auto-generated self-signed certificates:

# Generate certificates (or use existing)
openssl req -x509 -newkey rsa:4096 \
  -keyout server-key.pem -out server-cert.pem \
  -days 365 -nodes

# Start server with certificates
geode serve \
  --cert /etc/geode/certs/server-cert.pem \
  --key /etc/geode/certs/server-key.pem

Set Up Data Directory

Choose a persistent data directory location:

# Create data directory
sudo mkdir -p /var/lib/geode
sudo chown $(whoami):$(whoami) /var/lib/geode

# Start server with custom data directory
geode serve --data-dir /var/lib/geode

Configure System Service

For production, set up Geode as a system service:

systemd (Linux):

# Create service file
sudo vim /etc/systemd/system/geode.service

# Enable and start service
sudo systemctl enable geode
sudo systemctl start geode

See Deployment Guide for complete service configuration.

Troubleshooting

Build Errors

Symptom: Build fails with “command not found: zig”

Solution: Install Zig 0.1.0+ from ziglang.org

Port Binding Errors

Symptom: “address already in use” when starting server

Solution: Check if another process is using port 3141:

lsof -i :3141
kill -9 <PID>

Permission Errors

Symptom: “permission denied” when accessing data directory

Solution: Ensure proper ownership and permissions:

sudo chown -R $(whoami):$(whoami) /var/lib/geode
chmod 755 /var/lib/geode

Next Steps

After installation:

Getting Help

For installation issues:

  1. Check the Troubleshooting Guide
  2. Review platform-specific requirements above
  3. Search existing issues on GitLab
  4. Report new issues with detailed system information and error logs

Pages

Install from Source

Build Geode from source with Zig compiler

6 min read