DocumentationNeuronDB Documentation
Documentation Branch: You are viewing documentation for the main branch (3.0.0-devel). Select a branch to view its documentation:
main (3.0.0-devel) - LatestREL2_STABLE (2.0.0) - StableREL1_STABLE (1.0.0) - StableGitHub Repository →

Install NeuronDB on PostgreSQL 16 to 18

Choose Installation Method

📌 Branch & Version Selection

NeuronDB has three branches with different versions. Choose based on your needs:

BranchVersionStatusBest For
main3.0.0-develLatestDevelopment, new features, latest improvements (default)
REL2_STABLE2.0.0StableProduction, stable v2.0 features
REL1_STABLE1.0.0StableProduction, stability, proven releases

Recommendation: Use main for new projects and REL1_STABLE for production deployments requiring maximum stability.

Method 1: Docker

MethodBest ForTime
DockerMost users, includes full ecosystem5 minutes
DEB/RPM PackagesUbuntu/Debian, Rocky Linux/RHEL2 minutes
Source BuildProduction, custom builds30+ minutes
AnsibleInfrastructure provisioning, multi-server deployments10+ minutes

💡 Note: Use Docker to get the complete ecosystem (NeuronDB + NeuronAgent + NeuronMCP + NeuronDesktop) running quickly with automatic configuration.

Method 1: Docker

Docker provides the easiest installation with all ecosystem components pre-configured. See the Docker Quick Start Guide for complete instructions.

Quick start with Docker (main branch - version 2.0.0)

# Clone main branch for version 2.0.0 (latest features, default)
git clone https://github.com/neurondb-ai/neurondb.git
cd neurondb
# Note: Default clone gets main branch with version 2.0.0

# Start all services (NeuronDB + NeuronAgent + NeuronMCP + NeuronDesktop)
docker compose up -d

# Verify services
docker compose ps

Quick start with Docker (REL1_STABLE branch - version 1.0.0, stable)

# Clone REL1_STABLE branch for version 1.0.0 (stable production release)
git clone -b REL1_STABLE https://github.com/neurondb-ai/neurondb.git
cd neurondb
# Note: REL1_STABLE branch provides version 1.0.0 (stable release)

# Start all services
docker compose up -d

# Verify services
docker compose ps

This installs and starts:

  • NeuronDB (PostgreSQL with extension) on port 5433
  • NeuronAgent (REST API) on port 8080
  • NeuronMCP (MCP server)
  • NeuronDesktop (Web UI) on port 3000

View complete Docker installation guide →

Docker Images from GitHub Container Registry

Pre-built Docker images are available from GitHub Container Registry (GHCR). Pull specific versions:

Pull Docker images

# Pull latest images (version 2.0 from main branch)
docker compose pull

# Pull specific version (example)
docker pull ghcr.io/neurondb/neurondb-postgres:v2.0.0-pg17-cpu

# For version 1.0 (stable release from REL1_STABLE branch)
docker pull ghcr.io/neurondb/neurondb-postgres:v2.0.0-pg17-cpu

# Start services
docker compose up -d

📦 Version Information:

  • Version 2.0 (main branch): Latest features, improvements, and bug fixes
  • Version 1.0 (REL1_STABLE branch): Stable production release, for production deployments

Available image tags include variants for PostgreSQL 16/17/18 and GPU profiles (CPU, CUDA, ROCm, Metal). See GHCR packages for all available images.

Method 2: DEB/RPM Packages

Install NeuronDB using native package managers for Ubuntu/Debian (DEB) or Rocky Linux/RHEL (RPM). Packages are available from GitHub Releases.

Ubuntu / Debian (DEB)

Install DEB package (main branch - version 2.0.0)

# Download version 2.0.0 DEB package from GitHub Releases
# Visit: https://github.com/neurondb-ai/neurondb/releases
# Look for releases tagged with v2.0.0 (from main branch)

# Install package
sudo dpkg -i neurondb_2.0.0_amd64.deb

# Install dependencies if needed
sudo apt-get install -f

# Verify installation
psql -d postgres -c "CREATE EXTENSION neurondb;"
psql -d postgres -c "SELECT extversion FROM pg_extension WHERE extname = 'neurondb';"
# Expected output: 2.0

Install DEB package (REL1_STABLE branch - version 1.0.0)

# Download version 1.0.0 DEB package from GitHub Releases
# Visit: https://github.com/neurondb-ai/neurondb/releases
# Look for releases tagged with v2.0.0 (from main branch) or v1.0.0 (from REL1_STABLE branch)

# Install package
sudo dpkg -i neurondb_1.0.0_amd64.deb

# Install dependencies if needed
sudo apt-get install -f

# Verify installation
psql -d postgres -c "CREATE EXTENSION neurondb;"
psql -d postgres -c "SELECT extversion FROM pg_extension WHERE extname = 'neurondb';"
# Expected output: 1.0

Rocky Linux / RHEL (RPM)

Install RPM package (main branch - version 2.0.0)

# Download version 2.0.0 RPM package from GitHub Releases
# Visit: https://github.com/neurondb-ai/neurondb/releases
# Look for releases tagged with v2.0.0 (from main branch)

# Install package
sudo rpm -ivh neurondb-2.0.0-1.x86_64.rpm

# Or use yum/dnf
sudo yum install neurondb-2.0.0-1.x86_64.rpm

# Verify installation
psql -d postgres -c "CREATE EXTENSION neurondb;"
psql -d postgres -c "SELECT extversion FROM pg_extension WHERE extname = 'neurondb';"
# Expected output: 2.0

Install RPM package (REL1_STABLE branch - version 1.0.0)

# Download version 1.0.0 RPM package from GitHub Releases
# Visit: https://github.com/neurondb-ai/neurondb/releases
# Look for releases tagged with v2.0.0 (from main branch) or v1.0.0 (from REL1_STABLE branch)

# Install package
sudo rpm -ivh neurondb-1.0.0-1.x86_64.rpm

# Or use yum/dnf
sudo yum install neurondb-1.0.0-1.x86_64.rpm

# Verify installation
psql -d postgres -c "CREATE EXTENSION neurondb;"
psql -d postgres -c "SELECT extversion FROM pg_extension WHERE extname = 'neurondb';"
# Expected output: 1.0

📦 Package Availability: DEB and RPM packages are built for each release starting with v2.0.0. Download packages from GitHub Releases.

Note: Package installation only includes the NeuronDB PostgreSQL extension. For the complete ecosystem (NeuronAgent, NeuronMCP, NeuronDesktop), use Docker or build from source.

Method 3: Source Build

Build NeuronDB from source for production deployments or custom configurations. This installs only the PostgreSQL extension; you'll need to separately build NeuronAgent, NeuronMCP, and NeuronDesktop if you want the full ecosystem.

Continue reading below for platform-specific source build instructions.

Method 4: Ansible

Use Ansible automation for infrastructure provisioning and deployment of the NeuronDB ecosystem across development, staging, and production environments. Ansible complements Docker/Kubernetes scripts by handling OS-level system configuration, infrastructure provisioning, and service deployment.

✨ What Ansible Provides

  • OS-level system configuration - Package installation, user/group creation, system tuning
  • Infrastructure provisioning - Firewall, security hardening, SSL/TLS certificates
  • PostgreSQL installation and configuration - Repository setup, database configuration
  • NeuronDB extension build and installation - Build dependencies, compilation, installation
  • Service deployment - NeuronAgent, NeuronMCP, NeuronDesktop setup and configuration
  • Backup and restore operations - Database backup automation
  • Maintenance tasks - System updates, database VACUUM, log cleanup

Quick Start

Deploy complete ecosystem with Ansible

# 1. Clone repository
git clone https://github.com/neurondb-ai/neurondb.git
cd neurondb/ansible

# 2. Configure inventory
vi inventory/hosts.yml

# 3. Configure variables
vi group_vars/production.yml

# 4. Deploy to all hosts in production
ansible-playbook playbooks/site.yml -i inventory/hosts.yml --limit production

# 5. Verify deployment
ansible all -i inventory/hosts.yml -m shell -a "systemctl status postgresql neuronagent neuronmcp"

Prerequisites

  • Ansible - Install via brew install ansible (macOS) or apt-get install ansible (Ubuntu/Debian)
  • SSH Access - SSH key-based authentication to target hosts with sudo/root access
  • Python 3 - Python 3.6+ required on target hosts

Deploy Individual Components

Component-specific deployment

# Deploy only infrastructure
ansible-playbook playbooks/infrastructure.yml -i inventory/hosts.yml

# Deploy only NeuronDB
ansible-playbook playbooks/deploy-neurondb.yml -i inventory/hosts.yml

# Deploy only NeuronAgent
ansible-playbook playbooks/deploy-neuronagent.yml -i inventory/hosts.yml

# Deploy only NeuronMCP
ansible-playbook playbooks/deploy-neuronmcp.yml -i inventory/hosts.yml

# Deploy only NeuronDesktop
ansible-playbook playbooks/deploy-neurondesktop.yml -i inventory/hosts.yml

View complete Ansible deployment guide →

💡 Best For: Ansible is ideal for infrastructure provisioning, multi-server deployments, and environments where you need fine-grained control over OS-level configuration. For quick single-server setups, Docker is recommended.

Prerequisites (Source Build)

Before building from source, ensure you have:

  • PostgreSQL 16, 17, or 18 with superuser access
  • gcc/clang toolchain, make, autoconf, libtool
  • PostgreSQL server development headers
  • Optional: CUDA or ROCm drivers for GPU acceleration

Verify that pg_config points to your target PostgreSQL installation before compiling.

Ubuntu / Debian

Install system packages, fetch NeuronDB sources, and compile against PostgreSQL 17 deb packages.

Install PostgreSQL

PostgreSQL packages

sudo apt-get update
sudo apt-get install -y postgresql-17 \
    postgresql-server-dev-17 \
    postgresql-contrib-17

Install build dependencies

Build prerequisites

sudo apt-get install -y build-essential \
    libcurl4-openssl-dev \
    libssl-dev \
    zlib1g-dev \
    pkg-config

Compile & install

Build NeuronDB (main branch - version 2.0.0)

# Clone main branch for version 2.0.0
git clone https://github.com/neurondb-ai/neurondb.git
cd neurondb/NeuronDB
make PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config
sudo make install PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config

Build NeuronDB (REL1_STABLE branch - version 1.0.0)

# Clone REL1_STABLE branch for version 1.0.0 (stable production release)
git clone -b REL1_STABLE https://github.com/neurondb-ai/neurondb.git
cd neurondb/NeuronDB
make PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config
sudo make install PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config

💡 Branch Selection: Use main branch for version 2.0 (latest features) or REL1_STABLE branch for version 1.0 (stable production release).

Verify artifacts

Installed files

ls -lh /usr/lib/postgresql/17/lib/neurondb.so
ls -lh /usr/share/postgresql/17/extension/neurondb*

macOS (Homebrew)

Build NeuronDB against Homebrew PostgreSQL. Requires Xcode CLI tools and sudo for installation.

Install PostgreSQL 17

Homebrew setup

brew install postgresql@17
brew services start postgresql@17

Compile & install

Build NeuronDB (Version 2.0 - main branch)

# Clone repository (defaults to main branch for version 2.0)
git clone https://github.com/neurondb-ai/neurondb.git
cd neurondb/NeuronDB
make PG_CONFIG=/opt/homebrew/opt/postgresql@17/bin/pg_config
sudo make install PG_CONFIG=/opt/homebrew/opt/postgresql@17/bin/pg_config

Build NeuronDB (REL1_STABLE branch - version 1.0.0)

# Clone REL1_STABLE branch for version 1.0.0 (stable production release)
git clone -b REL1_STABLE https://github.com/neurondb-ai/neurondb.git
cd neurondb/NeuronDB
make PG_CONFIG=/opt/homebrew/opt/postgresql@17/bin/pg_config
sudo make install PG_CONFIG=/opt/homebrew/opt/postgresql@17/bin/pg_config

Rocky Linux / RHEL

Install PostgreSQL from the PGDG repository, then build NeuronDB against the RPM tooling.

Install PostgreSQL packages

PostgreSQL 17

sudo dnf install -y \
    postgresql17-server \
    postgresql17-devel \
    postgresql17-contrib

Install build dependencies

Build prerequisites

sudo dnf install -y \
    gcc \
    make \
    curl-devel \
    openssl-devel \
    zlib-devel

Compile & install

Build NeuronDB (main branch - version 2.0.0)

# Clone main branch for version 2.0.0
git clone https://github.com/neurondb-ai/neurondb.git
cd neurondb/NeuronDB
make PG_CONFIG=/usr/pgsql-17/bin/pg_config
sudo make install PG_CONFIG=/usr/pgsql-17/bin/pg_config

Build NeuronDB (REL1_STABLE branch - version 1.0.0)

# Clone REL1_STABLE branch for version 1.0.0 (stable production release)
git clone -b REL1_STABLE https://github.com/neurondb-ai/neurondb.git
cd neurondb/NeuronDB
make PG_CONFIG=/usr/pgsql-17/bin/pg_config
sudo make install PG_CONFIG=/usr/pgsql-17/bin/pg_config

Post-installation checks

Enable the extension, verify metadata, and confirm NeuronDB is available across your cluster.

Register extension

Initialize NeuronDB

-- Connect to target database
\c my_database

-- Create extension
CREATE EXTENSION neurondb;

-- Confirm version
SELECT extversion
FROM   pg_extension
WHERE  extname = 'neurondb';

Upgrade from version 1.0 to 2.0

If you're upgrading from NeuronDB 1.0 (REL1_STABLE branch) to version 2.0 (main branch), follow these steps:

Important: Version 2.0.0 is available on the main branch. The upgrade path requires switching from REL1_STABLE to main branch.

Upgrade extension

-- Check current version
SELECT extversion FROM pg_extension WHERE extname = 'neurondb';

-- Upgrade to version 2.0 (requires main branch installation)
ALTER EXTENSION neurondb UPDATE TO '2.0';

-- Verify upgrade
SELECT extversion FROM pg_extension WHERE extname = 'neurondb';

The upgrade script neurondb--1.0--2.0.sql will automatically run during the upgrade process. This ensures compatibility between versions and preserves all your data and indexes.Note: Make sure you've installed NeuronDB from the main branch before running the upgrade.

Optional GPU configuration

postgresql.conf

# Enable GPU acceleration
neurondb.gpu_enabled = on
neurondb.gpu_backend = 'cuda'  # or 'rocm'
neurondb.gpu_memory_pool_mb = 2048

Compatibility

NeuronDB supports:

  • PostgreSQL Versions: 16, 17, 18 (full feature support)
  • Operating Systems: Linux (Ubuntu 20.04+, Debian 11+, RHEL 8+), macOS 13+ (Ventura), macOS 14+ (Sonoma)
  • GPU Backends: CUDA (NVIDIA), ROCm (AMD), Metal (Apple Silicon)
  • Architectures: linux/amd64, linux/arm64

📋 Detailed Compatibility Matrix: For complete compatibility information including CI testing details, version-specific notes, and known issues, see COMPATIBILITY.md in the repository.

Next Steps

PreviousGetting Started
NextConfiguration