Configuration Guide¶

HiveMatrix uses a centralized configuration system managed by Helm. This guide explains how to configure the platform.

Configuration Architecture¶

Configuration Files¶

hivematrix-helm/
├── apps_registry.json           # Source of truth - service definitions
├── master_config.json           # System-wide configuration
├── services.json                # Auto-generated service list
├── master_services.json         # Auto-generated with master config
└── instance/configs/            # Per-service configs (auto-generated)
    ├── core.conf
    ├── codex.conf
    ├── ledger.conf
    └── ...

Important: Only edit apps_registry.json and master_config.json. The other files are auto-generated.

Configuration Hierarchy¶

apps_registry.json - Defines which services exist and their dependencies
master_config.json - System-wide settings (hostname, databases, keys)
Service configs - Generated by combining registry + master config

Master Configuration¶

Edit instance/configs/master_config.json:

{
  "system": {
    "environment": "production",
    "log_level": "INFO",
    "secret_key": "your-secret-key-here",
    "hostname": "your-domain.com"
  },
  "databases": {
    "postgresql": {
      "host": "localhost",
      "port": 5432,
      "admin_user": "postgres"
    },
    "neo4j": {
      "uri": "bolt://localhost:7687",
      "user": "neo4j",
      "password": "your-neo4j-password"
    }
  },
  "keycloak": {
    "client_secret": "your-keycloak-secret"
  }
}

System Settings¶

Setting	Description	Default
`environment`	Deployment environment	`production`
`log_level`	Logging verbosity	`INFO`
`secret_key`	Flask secret key (generate with `python -c 'import secrets; print(secrets.token_hex())'`)	Auto-generated
`hostname`	Public hostname or IP	`localhost`

Database Settings¶

PostgreSQL¶

Setting	Description	Default
`host`	PostgreSQL server	`localhost`
`port`	PostgreSQL port	`5432`
`admin_user`	Admin username	`postgres`

Neo4j (Optional)¶

Setting	Description	Default
`uri`	Neo4j connection string	`bolt://localhost:7687`
`user`	Neo4j username	`neo4j`
`password`	Neo4j password	Set during install

Service Registry¶

Edit apps_registry.json to define available services:

{
  "core_apps": {
    "core": {
      "name": "HiveMatrix Core",
      "description": "Authentication & service registry",
      "git_url": "https://github.com/ruapotato/hivematrix-core",
      "port": 5000,
      "required": true,
      "dependencies": ["postgresql"],
      "install_order": 1
    }
  },
  "default_apps": {
    "codex": {
      "name": "HiveMatrix Codex",
      "description": "Central data hub",
      "git_url": "https://github.com/ruapotato/hivematrix-codex",
      "port": 5010,
      "required": false,
      "dependencies": ["postgresql", "core"]
    }
  }
}

Service Definition Fields¶

Field	Description	Required
`name`	Display name	Yes
`description`	Service description	Yes
`git_url`	GitHub repository URL	Yes
`port`	Service port number	Yes
`required`	Must be installed	Yes
`dependencies`	List of dependencies	Yes
`install_order`	Installation sequence	Optional

Syncing Configuration¶

After editing configuration files, sync changes to all services:

cd hivematrix-helm
source pyenv/bin/activate

# Update service configs from registry
python install_manager.py update-config

# Sync master config to all services
python config_manager.py sync-all

# Restart services to apply changes
./stop.sh
./start.sh

Configuration Sync Process¶

update-config reads apps_registry.json and generates services.json and master_services.json
sync-all copies master config and services list to each service's instance/ directory
Services read their config files on startup

Service-Specific Configuration¶

Some services have additional configuration in their own config files:

Codex Configuration¶

instance/configs/codex.conf:

[database]
connection_string = postgresql://codex_user:password@localhost:5432/codex_db

[integrations]
freshservice_api_key = your-api-key
freshservice_domain = your-domain.freshservice.com
datto_api_key = your-datto-key
datto_api_secret = your-datto-secret
datto_api_url = https://your-instance.centrastage.net

KnowledgeTree Configuration¶

instance/configs/knowledgetree.conf:

[database]
neo4j_uri = bolt://localhost:7687
neo4j_user = neo4j
neo4j_password = your-password

[services]
codex_url = http://localhost:5010
core_url = http://localhost:5000

Brainhair Configuration¶

instance/configs/brainhair.conf:

[anthropic]
api_key = your-anthropic-api-key

[services]
codex_url = http://localhost:5010
ledger_url = http://localhost:5030
core_url = http://localhost:5000

[security]
filter_pii = true
require_approval = true

Environment Variables¶

Services also support environment variables for sensitive data:

# Set in shell before starting
export ANTHROPIC_API_KEY="your-key"
export FRESHSERVICE_API_KEY="your-key"

# Or create .env file (not recommended for production)
echo "ANTHROPIC_API_KEY=your-key" > .env

Port Configuration¶

Services use fixed ports defined in apps_registry.json. To change ports:

Edit the port number in apps_registry.json
Run python install_manager.py update-config
Restart services

Port Assignments:

Service	Port	Protocol
Nexus	443	HTTPS
Core	5000	HTTP
Helm	5004	HTTP
Codex	5010	HTTP
Archive	5012	HTTP
KnowledgeTree	5020	HTTP
Ledger	5030	HTTP
Template	5040	HTTP
Brainhair	5050	HTTP
Keycloak	8080	HTTP

SSL/TLS Configuration¶

Development (Self-Signed Certificate)¶

Helm generates a self-signed certificate automatically:

hivematrix-nexus/instance/ssl/
├── cert.pem     # Certificate
└── key.pem      # Private key

Production (Let's Encrypt)¶

For production, use Let's Encrypt:

# Install certbot
sudo apt install certbot

# Get certificate
sudo certbot certonly --standalone -d your-domain.com

# Update Nexus config
cd hivematrix-nexus
# Edit app.py to use /etc/letsencrypt/live/your-domain.com/

# Restart Nexus
cd ../hivematrix-helm
./stop.sh && ./start.sh

Keycloak Configuration¶

Keycloak settings are in master_config.json:

{
  "keycloak": {
    "client_secret": "YHl9bhq2TpUuiKPF8O273W587TfiYwdJ"
  }
}

The client secret is generated during initial setup. To regenerate:

Log in to Keycloak admin console (http://localhost:8080)
Go to Clients > hivematrix
Go to Credentials tab
Regenerate secret
Update master_config.json with new secret
Restart services

Logging Configuration¶

Log Levels¶

Set in master_config.json:

{
  "system": {
    "log_level": "DEBUG"  // DEBUG, INFO, WARNING, ERROR, CRITICAL
  }
}

Log Locations¶

hivematrix-helm/logs/
├── core.stdout.log
├── core.stderr.log
├── codex.stdout.log
├── codex.stderr.log
├── keycloak.stdout.log
└── ...

Centralized Logging¶

Services send logs to Helm's database:

# View logs via CLI
cd hivematrix-helm
source pyenv/bin/activate
python logs_cli.py --service core --tail 100

# Or via Helm web UI
# http://localhost:5004/logs

Backup Configuration¶

Configure automated backups:

# Edit crontab
sudo crontab -e

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

See Backup & Restore for details.

Firewall Configuration¶

Generate and apply firewall rules:

cd hivematrix-helm
source pyenv/bin/activate

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

# Review
cat secure_firewall.sh

# Apply
sudo bash secure_firewall.sh

This configures ufw to: - Allow SSH (port 22) - Allow HTTPS (port 443) - Block all other external access - Allow localhost connections

Performance Tuning¶

Database Optimization¶

PostgreSQL¶

Edit /etc/postgresql/*/main/postgresql.conf:

shared_buffers = 256MB          # 25% of RAM
effective_cache_size = 1GB      # 50-75% of RAM
work_mem = 16MB
maintenance_work_mem = 128MB
max_connections = 100

Restart PostgreSQL:

sudo systemctl restart postgresql

Neo4j¶

Edit /etc/neo4j/neo4j.conf:

dbms.memory.heap.initial_size=512m
dbms.memory.heap.max_size=2g
dbms.memory.pagecache.size=512m

Restart Neo4j:

sudo systemctl restart neo4j

Service Resources¶

Adjust Python worker processes in each service's run.py:

if __name__ == "__main__":
    app.run(
        host="127.0.0.1",
        port=5010,
        debug=DEBUG,
        threaded=True,  # Enable threading
        processes=1     # Increase for more workers
    )

Troubleshooting Configuration¶

Config Not Applied¶

If changes aren't taking effect:

# Regenerate all configs
cd hivematrix-helm
source pyenv/bin/activate
python install_manager.py update-config
python config_manager.py sync-all

# Restart services
./stop.sh
./start.sh

Service Can't Connect to Database¶

Check database config:

# Test PostgreSQL connection
psql -U postgres -h localhost -p 5432 -l

# Test Neo4j connection
cypher-shell -u neo4j -p your-password -d system

Port Conflicts¶

If a port is already in use:

# Find what's using the port
sudo lsof -i :5000

# Kill the process or change HiveMatrix port in apps_registry.json

Permission Errors¶

Fix file permissions:

cd ~/Work/hivematrix
sudo chown -R $USER:$USER .
chmod -R u+rw .

Next Steps¶

Review Services Overview to understand each service
Check Security Guide for production hardening
See Development Guide for creating custom services