Skip to content

Installation Guide

This guide will walk you through installing HiveMatrix from scratch on a Linux system.

System Requirements

Minimum Requirements

  • OS: Ubuntu 20.04 LTS or later (Debian-based Linux)
  • RAM: 4GB minimum, 8GB recommended
  • CPU: 2 cores minimum, 4 cores recommended
  • Disk: 20GB free space minimum
  • Network: Internet connection for package installation

Software Dependencies (Auto-installed by start.sh)

  • Python 3.10 or later
  • PostgreSQL 14 or later
  • Redis 5.x or later (for session storage and rate limiting)
  • Neo4j 5.x (optional, for KnowledgeTree)
  • Java 17 (for Keycloak)
  • Git
  • jq (JSON processor)

Quick Start

Complete installation workflow for Ubuntu 24.04.

Note: The start.sh script automatically installs most system dependencies (Python, PostgreSQL, Redis, Java, Git, jq). You only need to manually install Neo4j if you plan to use KnowledgeTree.

1. Manual Prerequisites (Optional)

Neo4j (Only if using KnowledgeTree)

# Install Java (required for Neo4j)
sudo apt install -y openjdk-17-jre-headless

# Add Neo4j repository
wget -O - https://debian.neo4j.com/neotechnology.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/neo4j.gpg
echo 'deb [signed-by=/usr/share/keyrings/neo4j.gpg] https://debian.neo4j.com stable latest' | sudo tee /etc/apt/sources.list.d/neo4j.list

# Install Neo4j
sudo apt update
sudo apt install -y neo4j

# Set initial password (remember this for KnowledgeTree config later)
sudo neo4j-admin dbms set-initial-password your-secure-password

# Enable and start Neo4j
sudo systemctl enable neo4j
sudo systemctl start neo4j

2. Install HiveMatrix

# Create HiveMatrix directory
mkdir ~/hivematrix
cd ~/hivematrix

# Clone the orchestration system
git clone https://github.com/skelhammer/hivematrix-helm
cd hivematrix-helm

# Run the installation (auto-installs all dependencies)
./start.sh

The start.sh script will automatically install and configure:

  1. ✓ System dependencies (Python, PostgreSQL, Redis, Java, Git, jq)
  2. ✓ Python virtual environment for each service
  3. ✓ Keycloak download and configuration (~200MB)
  4. ✓ Core and Nexus repositories
  5. ✓ Database setup (prompts for passwords, creates databases)
  6. ✓ SSL certificates for HTTPS (self-signed)
  7. ✓ Redis service for session persistence
  8. ✓ Service configuration and startup

No manual installation required - start.sh handles everything except Neo4j (optional).

After core installation completes, press Ctrl+C to stop start.sh.

3. Install Additional Services (Optional)

# Install individual services
python install_manager.py install codex         # Central data hub (5010)
python install_manager.py install ledger        # Billing & archival (5030)
python install_manager.py install knowledgetree # Knowledge base (5020, requires Neo4j)
python install_manager.py install brainhair     # AI assistant (5050, requires Claude Code CLI)
python install_manager.py install beacon        # Ticket dashboard (5001)

# Or install all default apps at once
python install_manager.py install-defaults

# Restart to activate new services
./start.sh

Service-Specific Setup:

Brainhair requires Claude Code CLI and additional dependencies: 

# Install Claude Code CLI (official Anthropic CLI)
# Option 1: NPM global install (recommended for Linux servers)
npm install -g @anthropic-ai/claude-code

# Option 2: macOS via Homebrew
brew install anthropic/anthropic/claude

# Option 3: Direct download
# Download from https://github.com/anthropics/claude-code/releases
# Place binary in ~/.local/bin/claude and chmod +x

# IMPORTANT: After installing, authenticate Claude Code:
claude  # Follow the OAuth login prompts

# The binary should be in one of these locations for systemd compatibility:
#   - ~/.local/bin/claude (preferred)
#   - /usr/local/bin/claude
#   - Or accessible via PATH

# Install spaCy model for NER (in brainhair's pyenv)
cd hivematrix-brainhair
source pyenv/bin/activate
python -m spacy download en_core_web_sm

# Presidio is installed via requirements.txt automatically

KnowledgeTree requires Neo4j (see step 1 if not already installed): 

# Configure Neo4j connection in instance/knowledgetree.conf
# URI: bolt://localhost:7687
# User: neo4j
# Password: your-neo4j-password

Core uses Redis for session persistence: 

# Redis is auto-installed by start.sh
# Verify it's running:
sudo systemctl status redis-server

# Configure in master_config.json (optional):
# "redis": {
#   "host": "localhost",
#   "port": 6379
# }

4. Access HiveMatrix

Open browser to https://YOUR_SERVER_IP:443 (use your server's actual IP address, not localhost)

Default credentials: - Username: admin - Password: admin

Important: Change the default password after first login!

Post-Installation

Monitor Installation

The installer provides detailed output:

================================================================
  HiveMatrix Helm - Orchestration System
================================================================

Verifying HiveMatrix installation...

================================================================
  Step 1: System Dependencies
================================================================

Checking Python...
✓ Python 3.12.3

Checking Git...
✓ Git installed

... (continues with each step)

After installation completes, you'll see:

================================================================
  HiveMatrix is Ready!
================================================================

  Login URL:         https://YOUR_SERVER_IP:443
  Helm Dashboard:    http://localhost:5004

  Default Login:
    Username: admin
    Password: admin

  Important: Use your server's IP address, not localhost!

================================================================

Verifying Installation

Check Service Status

cd hivematrix-helm
source pyenv/bin/activate
python service_manager.py status

Expected output:

================================================================================
HiveMatrix Service Status
================================================================================

KEYCLOAK
  Status:  running
  Health:  healthy
  Port:    8080

CORE
  Status:  running
  Health:  healthy
  Port:    5000

NEXUS
  Status:  running
  Health:  healthy
  Port:    443

... (other services)

Test Web Access

  1. Open browser to https://YOUR_SERVER_IP:443 (replace with your server's IP address)
  2. Note: https://localhost:443 will NOT work - you must use the server's actual IP address
  3. Example: https://192.168.1.100:443
  4. Accept self-signed certificate warning (on first visit)
  5. You should see the Keycloak login page
  6. Log in with admin/admin

Important: HiveMatrix requires accessing via IP address, not localhost, due to how the authentication system handles redirects.

Run Security Audit

cd hivematrix-helm
source pyenv/bin/activate
python security_audit.py --audit

This checks: - Service port bindings - Firewall status - SSL certificates - Database connections

Troubleshooting Installation

Port Already in Use

If you see "Address already in use" errors:

# Check what's using the port (e.g., port 443)
sudo lsof -i :443

# Stop the conflicting service or change HiveMatrix ports in services.json

PostgreSQL Connection Refused

If PostgreSQL isn't running:

# Start PostgreSQL
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Check status
sudo systemctl status postgresql

Keycloak Won't Start

If Keycloak fails to start:

# Check Java version (must be 21)
java -version

# Check Keycloak logs
tail -f logs/keycloak.stderr.log

# Restart Keycloak
cd ../keycloak-26.4.0
./bin/kc.sh stop
./bin/kc.sh start-dev

Permission Denied Errors

If you see permission errors:

# Fix ownership of HiveMatrix directory
cd ~/hivematrix
sudo chown -R $USER:$USER .

# Fix git directory permissions
cd hivematrix-helm
sudo chown -R $USER:$USER .git

Clean Installation

To start over from scratch:

# Stop all services
cd ~/hivematrix/hivematrix-helm
./stop.sh

# Remove all data (WARNING: This deletes everything!)
sudo systemctl stop neo4j
sudo -u postgres dropdb --if-exists core_db
sudo -u postgres dropdb --if-exists helm_db
sudo -u postgres dropdb --if-exists codex_db
sudo -u postgres dropdb --if-exists ledger_db
sudo -u postgres dropdb --if-exists brainhair_db
sudo -u postgres dropdb --if-exists knowledgetree_db

# Remove Keycloak data
rm -rf ../keycloak-26.4.0/data/*

# Restart installation
./start.sh

Autostart Configuration

HiveMatrix can be configured to start automatically on system boot using systemd.

Prerequisites

Before enabling autostart, ensure system services are installed and running:

# Required system services
sudo systemctl status postgresql
sudo systemctl status redis-server  # or redis on some systems

# Optional (only if using KnowledgeTree)
sudo systemctl status neo4j

All of these are automatically installed by start.sh on first run.

Enable Autostart

cd hivematrix-helm
sudo ./install_autostart.sh

This will: - Create a systemd service unit for HiveMatrix - Configure it to start on boot after PostgreSQL and Redis - Set up proper user permissions - Enable the service - Configure port 443 binding capability

Manage Autostart Service

# Check status
sudo systemctl status hivematrix

# Start/stop/restart
sudo systemctl start hivematrix
sudo systemctl stop hivematrix
sudo systemctl restart hivematrix

# View logs
sudo journalctl -u hivematrix -f

The autostart service will: - Start all HiveMatrix services on boot - Run as your user (not root) - Automatically restart services if they crash - Log to systemd journal

Disable/Uninstall Autostart

To remove the systemd service:

cd hivematrix-helm
sudo ./uninstall_autostart.sh

This will: - Stop the HiveMatrix service if running - Disable auto-start on boot - Remove the systemd service file - Keep HiveMatrix installed (can still run with ./start.sh)

Autostart Best Practices

  1. Test First: Make sure HiveMatrix works with ./start.sh before enabling autostart
  2. Monitor Logs: Check sudo journalctl -u hivematrix for startup issues
  3. Database Dependencies: Systemd ensures PostgreSQL and Redis start before HiveMatrix
  4. Service Order: HiveMatrix waits for network, PostgreSQL, and Redis to be ready
  5. Resource Limits: The systemd unit includes appropriate memory/CPU limits

Post-Installation Configuration

Change Default Password

  1. Log in with admin/admin
  2. Click your name in top right
  3. Go to "Account Settings"
  4. Change password

Configure Firewall

For production deployments:

cd hivematrix-helm
source pyenv/bin/activate

# Generate firewall rules
python security_audit.py --generate-firewall

# Review the script
cat secure_firewall.sh

# Apply firewall rules
sudo bash secure_firewall.sh

Set Up SSL Certificate

For production with a real domain:

# Install certbot
sudo apt install certbot

# Get Let's Encrypt certificate
sudo certbot certonly --standalone -d your-domain.com

# Update Nexus to use the certificate
# Edit nexus config to point to /etc/letsencrypt/live/your-domain.com/

Configure Backups

Set up automated backups:

# Create backup script
sudo crontab -e

# Add daily backup at 2 AM
0 2 * * * cd /home/your-user/hivematrix/hivematrix-helm && /usr/bin/python3 backup.py >> /var/log/hivematrix-backup.log 2>&1

Next Steps

Getting Help

If you encounter issues:

  1. Check the troubleshooting section above
  2. Review logs in hivematrix-helm/logs/
  3. Run the security audit for configuration issues
  4. Open an issue on GitHub with logs and error messages