Ansible Infrastructure Provisioning | NeuronDB Deployment

Overview

The Ansible automation complements existing Docker/Kubernetes scripts by handling infrastructure provisioning and deployment of the NeuronDB ecosystem across development, staging, and production environments.

✨ What Ansible Handles

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

Location: All Ansible automation is located in the ansible/ directory of the NeuronDB repository.

Quick Start

Get started with Ansible deployment in minutes:

Deploy complete ecosystem

# 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

1. Ansible Installation

Install Ansible

# macOS
brew install ansible

# Ubuntu/Debian
sudo apt-get install ansible

# RHEL/CentOS/Rocky
sudo yum install ansible

2. SSH Access

SSH key-based authentication to target hosts
Sudo/root access on target hosts

3. Python 3

Python 3.6+ required on target hosts

Initial Setup

Configure Inventory

Edit inventory file

# Edit inventory/hosts.yml with your server details
vi inventory/hosts.yml

Configure Variables

Edit environment variables

# Edit group_vars for your environment
vi group_vars/production.yml

Set Up Ansible Vault (for secrets)

Configure Ansible Vault

# Create vault password file
echo "your-vault-password" > .vault_pass
chmod 600 .vault_pass

# Encrypt sensitive variables
ansible-vault encrypt group_vars/production.yml

# Edit encrypted file
ansible-vault edit group_vars/production.yml

# View encrypted file
ansible-vault view group_vars/production.yml

Inventory Setup

Basic Inventory

Edit inventory/hosts.yml:

Example inventory structure

all:
  children:
    production:
      hosts:
        prod-neurondb-01:
          ansible_host: 10.0.1.10
          ansible_user: root
        prod-neurondb-02:
          ansible_host: 10.0.1.11
          ansible_user: root
    development:
      hosts:
        dev-neurondb-01:
          ansible_host: 10.0.2.10
          ansible_user: ubuntu

Host-Specific Variables

Create inventory/host_vars/prod-neurondb-01.yml:

Host-specific configuration

neurondb_maintenance_work_mem: "1GB"
postgresql_max_connections: 300

Configuration

Global Variables (group_vars/all.yml)

Component versions
Installation paths
Service users
Build options

Environment Variables

Development (group_vars/development.yml): Lower resources, debug enabled
Staging (group_vars/staging.yml): Production-like configuration
Production (group_vars/production.yml): Optimized for performance and security

Directory Structure

Ansible directory layout

ansible/
├── ansible.cfg              # Ansible configuration
├── requirements.yml         # Ansible role dependencies
├── README.md               # Documentation
├── playbooks/              # Playbooks
│   ├── site.yml           # Main orchestration playbook
│   ├── infrastructure.yml  # Infrastructure provisioning
│   ├── deploy-*.yml        # Component deployment playbooks
│   ├── backup-restore.yml  # Backup and restore operations
│   └── maintenance.yml     # Maintenance tasks
├── roles/                  # Ansible roles
│   ├── common/            # Common system setup
│   ├── postgresql/        # PostgreSQL installation
│   ├── neurondb/          # NeuronDB extension
│   ├── neuronagent/       # NeuronAgent service
│   ├── neuronmcp/         # NeuronMCP service
│   ├── neurondesktop/     # NeuronDesktop service
│   ├── monitoring/        # Monitoring setup
│   └── security/          # Security hardening
├── inventory/              # Inventory files
│   ├── hosts.yml         # Host inventory
│   └── group_vars/        # Group-specific variables
├── group_vars/             # Environment variables
│   ├── all.yml           # Global variables
│   ├── development.yml    # Development environment
│   ├── staging.yml        # Staging environment
│   └── production.yml     # Production environment
└── files/                  # Static files
    ├── systemd/           # Systemd service files
    └── configs/          # Configuration templates

Playbooks

site.yml - Main Orchestration

Deploys the complete ecosystem:

Deploy complete ecosystem

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

# Deploy to specific host
ansible-playbook playbooks/site.yml -i inventory/hosts.yml --limit prod-neurondb-01

# Dry run (check mode)
ansible-playbook playbooks/site.yml -i inventory/hosts.yml --check

infrastructure.yml - Infrastructure Provisioning

Provisions OS-level infrastructure:

System packages
Firewall configuration
Security hardening
System tuning
SSL/TLS certificates

Deploy infrastructure

ansible-playbook playbooks/infrastructure.yml -i inventory/hosts.yml

Deploy Individual Components

Component-specific playbooks

# 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

backup-restore.yml - Database Operations

Backup and restore

# Create backup
ansible-playbook playbooks/backup-restore.yml -i inventory/hosts.yml --tags backup

# Restore from backup
ansible-playbook playbooks/backup-restore.yml -i inventory/hosts.yml   --tags restore   -e backup_file_path=/backups/neurondb/backup.dump

maintenance.yml - Maintenance Tasks

Maintenance operations:

System updates
Database VACUUM
Log cleanup
Backup cleanup

Run maintenance

ansible-playbook playbooks/maintenance.yml -i inventory/hosts.yml

Roles

common

OS-level setup:

Package installation
User/group creation
Directory structure
System limits
Log rotation

postgresql

PostgreSQL installation and configuration:

Repository setup
PostgreSQL installation
Configuration files
Database and user creation

neurondb

NeuronDB extension:

Build dependencies
Extension build
Extension installation
Verification

neuronagent

NeuronAgent service:

Go installation
Binary build
Configuration
Systemd service

neuronmcp

NeuronMCP service:

Go installation
Binary build
Configuration
Systemd service

neurondesktop

NeuronDesktop service:

Node.js installation
Go installation
API and frontend build
Systemd services

monitoring

Monitoring setup (Prometheus, Grafana).

security

Security hardening and firewall configuration.

Integration with Existing Scripts

The Ansible playbooks integrate with existing shell scripts:

neurondb-setup.sh

Used for package installation and setup verification.

neurondb-database.sh

Used for backup and restore operations:

backup-restore.yml calls neurondb-database.sh backup
backup-restore.yml calls neurondb-database.sh restore

neurondb-healthcheck.sh

Used for health verification:

deploy-neurondb.yml calls neurondb-healthcheck.sh quick
deploy-neuronagent.yml calls neurondb-healthcheck.sh health

Common Tasks

Deploy to New Server

Complete new server deployment

# 1. Add server to inventory
vi inventory/hosts.yml

# 2. Test connectivity
ansible all -i inventory/hosts.yml -m ping

# 3. Deploy infrastructure
ansible-playbook playbooks/infrastructure.yml -i inventory/hosts.yml --limit new-server

# 4. Deploy NeuronDB
ansible-playbook playbooks/deploy-neurondb.yml -i inventory/hosts.yml --limit new-server

# 5. Deploy services
ansible-playbook playbooks/site.yml -i inventory/hosts.yml --limit new-server

Update Configuration

Update service configuration

# Update configuration and restart services
ansible-playbook playbooks/deploy-neuronagent.yml -i inventory/hosts.yml   -e neuronagent_log_level=debug

Run Maintenance

Execute maintenance tasks

# Run maintenance tasks
ansible-playbook playbooks/maintenance.yml -i inventory/hosts.yml

Backup Database

Create database backup

# Create backup
ansible-playbook playbooks/backup-restore.yml -i inventory/hosts.yml   --tags backup

Using Tags

Run specific tasks with tags

# Run only infrastructure tasks
ansible-playbook playbooks/infrastructure.yml --tags firewall

# Skip certain tasks
ansible-playbook playbooks/site.yml --skip-tags backup

Parallel Execution

Deploy to multiple hosts in parallel

# Run on multiple hosts in parallel (10 at a time)
ansible-playbook playbooks/site.yml -i inventory/hosts.yml -f 10

Custom Variables

Override variables at runtime

# Override variables at runtime
ansible-playbook playbooks/deploy-neurondb.yml -i inventory/hosts.yml   -e postgresql_version=18   -e neurondb_version=2.0.0

Troubleshooting

Connection Issues

Test SSH connectivity

# Test SSH connectivity
ansible all -i inventory/hosts.yml -m ping

# Test with verbose output
ansible all -i inventory/hosts.yml -m ping -vvv

Permission Issues

Use become with specific user

# Use become with specific user
ansible-playbook playbooks/site.yml -i inventory/hosts.yml   --become --become-user=root

Service Not Starting

Check service status and logs

# Check service status
ansible all -i inventory/hosts.yml -m systemd   -a "name=neuronagent state=started"

# View logs
ansible all -i inventory/hosts.yml -m shell   -a "journalctl -u neuronagent -n 50"

Build Failures

Check build dependencies

# Check build dependencies
ansible all -i inventory/hosts.yml -m shell   -a "which gcc && which make && which pg_config"

# Check Go installation
ansible all -i inventory/hosts.yml -m shell   -a "go version"

Best Practices

Use Ansible Vault for Secrets
- Never commit unencrypted passwords
- Use vault for database passwords, API keys
Test in Development First
- Always test playbooks in development
- Use --check mode for dry runs
Version Control
- Commit inventory and playbooks
- Use tags for versioning
Idempotency
- Playbooks are idempotent (safe to re-run)
- Use --check to preview changes
Limit Scope
- Use --limit to target specific hosts
- Use tags to run specific tasks
Security Considerations
- Use SSH key-based authentication
- Encrypt all sensitive variables with Vault
- Enable firewall rules in production
- Use dedicated service users (not root)
- Restrict file permissions

Additional Resources

Ansible README - Complete Ansible documentation in repository
Ansible Directory - All Ansible automation source code
Operational Scripts - Shell scripts for deployment
Kubernetes Deployment - Cloud-native deployment guide
Observability Stack - Monitoring setup

💡 Tip: Ansible playbooks are idempotent and safe to re-run. Use --check mode to preview changes before applying them.