aitbc/docs/deployment/SETUP.md

AITBC Setup Guide

Quick Setup (New Host)

The main setup script lives at scripts/setup.sh.

Run this single command on any new host to install AITBC:

sudo bash <(curl -sSL https://github.com/oib/AITBC/raw/branch/main/scripts/setup.sh)

Or clone and run manually:

sudo git clone https://github.com/oib/AITBC.git /opt/aitbc
cd /opt/aitbc
sudo chmod +x scripts/setup.sh
sudo ./scripts/setup.sh

What scripts/setup.sh Does

1. Prerequisites Check

   • Verifies Python 3.13.5+, pip3, git, systemd
   • Checks for root privileges

2. Repository Setup

   • Clones AITBC repository to /opt/aitbc
   • Handles multiple repository URLs for reliability

3. Virtual Environments

   • Creates Python venvs for each service
   • Installs dependencies from requirements.txt when available
   • Falls back to core dependencies if requirements missing

4. Runtime Directories

   • Creates standard Linux directories:
     • /var/lib/aitbc/keystore/ - Blockchain keys
     • /var/lib/aitbc/data/ - Database files
     • /var/lib/aitbc/logs/ - Application logs
     • /etc/aitbc/ - Configuration files
   • Sets proper permissions and ownership

5. PostgreSQL Databases

   • Installs PostgreSQL if not present
   • Creates databases: aitbc_coordinator, aitbc_exchange, aitbc_wallet, aitbc_marketplace, aitbc_governance, aitbc_trading, aitbc_gpu, aitbc_ai, aitbc_mempool
   • Creates dedicated users for each database
   • Grants necessary privileges
   • Uses centralized script: /opt/aitbc/infra/scripts/setup_postgresql_databases.sh

6. Systemd Services

   • Installs service files to /etc/systemd/system/
   • Enables auto-start on boot
   • Provides fallback manual startup

7. Service Management

   • Creates /opt/aitbc/start-services.sh for manual control
   • Uses /opt/aitbc/scripts/monitoring/health_check.sh for monitoring
   • Sets up logging to /var/log/aitbc-*.log

Runtime Directories

AITBC uses standard Linux system directories for runtime data:

/var/lib/aitbc/
├── keystore/     # Blockchain private keys (700 permissions)
├── data/         # Database files (.db, .sqlite)
└── logs/         # Application logs

/etc/aitbc/       # Configuration files
/var/log/aitbc/   # System logging (symlink)

Security Notes

• Keystore: Restricted to root/aitbc user only
• Data: Writable by services, readable by admin
• Logs: Rotated automatically by logrotate

Service Endpoints

Service	Port	Health Endpoint
Wallet API	8003	http://localhost:8003/health
Exchange API	8001	http://localhost:8001/api/health
Coordinator API	8000	http://localhost:8011/health
Blockchain RPC	8006	http://localhost:8006/health

Management Commands

# Check service health
/opt/aitbc/scripts/monitoring/health_check.sh

# Restart all services
/opt/aitbc/start-services.sh

# View logs (new standard locations)
tail -f /var/lib/aitbc/logs/aitbc-wallet.log
tail -f /var/lib/aitbc/logs/aitbc-coordinator.log
tail -f /var/lib/aitbc/logs/aitbc-exchange.log

# Check keystore
ls -la /var/lib/aitbc/keystore/

# Systemd control
systemctl status aitbc-wallet
systemctl restart aitbc-coordinator-api
systemctl stop aitbc-exchange-api

Troubleshooting

Services Not Starting

1. Check logs: tail -f /var/lib/aitbc/logs/aitbc-*.log
2. Verify ports: netstat -tlnp | grep ':800'
3. Check processes: ps aux | grep python
4. Verify runtime directories: ls -la /var/lib/aitbc/

Missing Dependencies

The setup script handles missing requirements.txt files by installing core dependencies:

• fastapi
• uvicorn
• pydantic
• httpx
• python-dotenv

Port Conflicts

Services use these default ports. If conflicts exist:

1. Kill conflicting processes: kill <pid>
2. Modify service files to use different ports
3. Restart services

Development Mode

For development with manual control:

cd /opt/aitbc/apps/wallet
source .venv/bin/activate
python simple_daemon.py

cd /opt/aitbc/apps/exchange
source .venv/bin/activate
python simple_exchange_api.py

cd /opt/aitbc/apps/coordinator-api/src
source ../.venv/bin/activate
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

Configuration Files

AITBC uses two main configuration files located in /etc/aitbc/:

/etc/aitbc/blockchain.env

Contains blockchain-specific environment variables:

• Chain ID and network configuration
• RPC and P2P binding settings
• Database and Redis connections
• Block production settings
• Gossip and sync configuration

/etc/aitbc/node.env

Contains node-specific environment variables:

• Node ID and island ID
• Node role (genesis/follower)
• P2P port configuration
• Node-specific settings

Note: AITBC does NOT use /etc/aitbc/.env. All configuration should be in blockchain.env and node.env.

Configuration Examples

Pre-configured example files are available in /opt/aitbc/examples/ for quick setup:

• Examples README - Complete guide to all configuration examples
• blockchain.env.open-island - Pre-configured for hub.aitbc.bubuit.net open island
• node.env.open-island - Node-specific configuration for open island
• blockchain.env.example - General blockchain configuration template
• node.env.example - General node configuration template

Quick Setup for Open Island:

sudo cp /opt/aitbc/examples/blockchain.env.open-island /etc/aitbc/blockchain.env
sudo cp /opt/aitbc/examples/node.env.open-island /etc/aitbc/node.env

Production Considerations

For production deployment:

1. Configure /etc/aitbc/blockchain.env with proper environment variables
2. Configure /etc/aitbc/node.env with node-specific settings
3. Set up reverse proxy (nginx)
4. Configure SSL certificates manually outside scripts/setup.sh
5. Set up log rotation
6. Configure monitoring and alerts
7. Use proper database setup (PostgreSQL/Redis)

Hermes Skills Integration

AITBC includes documentation skills for Hermes agents. These skills enable automated operations and can be imported by Hermes agents to perform tasks:

• Documentation Skills - Complete skill library for Hermes agents:
  • aitbc-basic-operations.md - Basic CLI operations, wallet management, blockchain status
  • aitbc-marketplace.md - Marketplace operations, GPU provider registration, trading
  • aitbc-node-coordination.md - Multi-node coordination, git synchronization, blockchain sync
  • aitbc-wallet-management.md - Wallet creation, import/export, balance checks, deletion
  • aitbc-ai-operations.md - AI job submission, monitoring, resource allocation, GPU testing
  • aitbc-blockchain-troubleshooting.md - Blockchain troubleshooting, sync issues, P2P problems
  • aitbc-multi-node-operations.md - Multi-node operations, git sync, service restart, blockchain sync
  • aitbc-cli.md - CLI tool reference for training agents and workflow operations

These skills are located in docs/skills/ and follow the YAML frontmatter format required by Hermes for skill loading.

Open Island Testing

AITBC provides an open test island for software testing and agent coordination:

• Open Island Joining Guide - Complete guide for joining the hub.aitbc.bubuit.net open island:

  • Quick start setup for new nodes
  • P2P and RPC connectivity to the hub
  • hermes agent registration and cross-node communication
  • Blockchain synchronization with the open island
  • Troubleshooting and security guidelines

• hermes Agent Guide for Open Island - hermes-specific instructions for agents joining the open island:

  • hermes agent initialization and configuration
  • Agent wallet creation and registration
  • Cross-node communication patterns
  • hermes workflow integration
  • Testing procedures and best practices

The open island allows any agent to test AITBC software functionality without authentication requirements.