aitbc/packages/github/README.md

AITBC CLI & Services - GitHub Ready Packages

🚀 Quick Start for GitHub Cloners

One-Command Installation

curl -fsSL https://raw.githubusercontent.com/aitbc/aitbc/main/packages/github/install.sh | bash

Manual Installation

git clone https://github.com/aitbc/aitbc.git
cd aitbc/packages/github
./install.sh

📦 Available Packages

CLI Packages

• aitbc-cli_0.1.0_all.deb - Main CLI package (132KB)

Service Packages

• aitbc-node-service_0.1.0_all.deb - Blockchain node (8.4KB)
• aitbc-coordinator-service_0.1.0_all.deb - Coordinator API (8.4KB)
• aitbc-miner-service_0.1.0_all.deb - GPU miner (8.4KB)
• aitbc-marketplace-service_0.1.0_all.deb - Marketplace (8.4KB)
• aitbc-explorer-service_0.1.0_all.deb - Explorer (8.4KB)
• aitbc-wallet-service_0.1.0_all.deb - Wallet service (8.4KB)
• aitbc-multimodal-service_0.1.0_all.deb - Multimodal AI (8.4KB)
• aitbc-all-services_0.1.0_all.deb - Complete stack (8.4KB)

🎯 Installation Options

Option 1: CLI Only

./install.sh --cli-only

Option 2: Services Only

./install.sh --services-only

Option 3: Complete Installation

./install.sh --complete

Option 4: Custom Selection

./install.sh --packages aitbc-cli,aitbc-node-service,aitbc-miner-service

🖥️ Platform Support

Linux (Debian/Ubuntu)

# Debian 13 Trixie, Ubuntu 24.04+
sudo apt-get update
sudo apt-get install -y python3.13 python3.13-venv python3-pip
./install.sh

macOS (Mac Studio - Apple Silicon)

# Apple Silicon (M1/M2/M3/M4) - Mac Studio optimized
curl -fsSL https://raw.githubusercontent.com/aitbc/aitbc/main/packages/github/packages/macos-packages/install-macos-complete.sh | bash

# Alternative: Homebrew (when available)
brew install aitbc-cli

Windows (WSL2)

# Windows 10/11 with WSL2
wsl --install -d Debian
./install.sh

🔧 System Requirements

Minimum Requirements

• OS: Debian 13, Ubuntu 24.04+, or compatible
• Python: 3.13+ (auto-installed on Linux)
• Memory: 2GB RAM minimum
• Storage: 1GB free space
• Network: Internet connection for dependencies

Recommended Requirements

• OS: Debian 13 Trixie
• Python: 3.13+
• Memory: 8GB RAM
• Storage: 10GB free space
• GPU: NVIDIA CUDA (for mining services)

🛠️ Installation Script Features

Automatic Detection

• OS detection and compatibility check
• Python version verification
• Dependency installation
• Service user creation
• Permission setup

Package Management

• Dependency resolution
• Conflict detection
• Rollback capability
• Version verification

Post-Installation

• Service configuration
• Log rotation setup
• Health checks
• System integration

📁 Repository Structure

aitbc/
├── packages/github/
│   ├── install.sh              # Main installer
│   ├── install-macos.sh        # macOS installer
│   ├── install-windows.sh      # Windows/WSL installer
│   ├── packages/               # Package distribution
│   │   ├── debian-packages/    # Linux/Debian packages
│   │   └── macos-packages/     # macOS packages (CLI + Services)
│   ├── README.md               # Main documentation
│   └── docs/                   # Additional documentation
├── cli/                        # CLI source
├── systemd/                    # Service definitions
└── docs/                       # Full documentation

Update Management

Update CLI

./install.sh --update-cli

Update Services

./install.sh --update-services

Complete Update

./install.sh --update-all

🗑️ Uninstallation

Complete Removal

./install.sh --uninstall-all

CLI Only

./install.sh --uninstall-cli

Services Only

./install.sh --uninstall-services

🧪 Testing Installation

CLI Test

aitbc --version
aitbc --help
aitbc wallet balance

Services Test

sudo systemctl status aitbc-node.service
sudo journalctl -u aitbc-node.service -f

Health Check

./install.sh --health-check

🌐 Network Configuration

Default Ports

• Node: 30333 (P2P), 8006 (RPC)
• Coordinator: 8000 (API)
• Marketplace: 8001 (API)
• Explorer: 3000 (Web), 3001 (API)
• Wallet: 8002 (API)
• Multimodal: 8003 (API)

Firewall Setup

# Open required ports
sudo ufw allow 30333
sudo ufw allow 8000:8003/tcp
sudo ufw allow 3000:3001/tcp

🔒 Security Considerations

Package Verification

# Verify package checksums
sha256sum -c checksums.txt

Security Setup

# Create dedicated user
sudo useradd -r -s /usr/sbin/nologin aitbc

# Set proper permissions
sudo chown -R aitbc:aitbc /var/lib/aitbc
sudo chmod 755 /var/lib/aitbc

📊 Performance Tuning

CLI Optimization

# Enable shell completion
echo 'source /usr/share/aitbc/completion/aitbc_completion.sh' >> ~/.bashrc

# Set up aliases
echo 'alias aitbc="source /opt/aitbc/venv/bin/activate && aitbc"' >> ~/.bashrc

Service Optimization

# Optimize systemd services
sudo systemctl edit aitbc-node.service
# Add:
# [Service]
# LimitNOFILE=65536
# LimitNPROC=4096

🐛 Troubleshooting

Common Issues

1. Python Version Issues

   python3 --version  # Should be 3.13+
   

2. Permission Issues

   sudo chown -R aitbc:aitbc /var/lib/aitbc
   

3. Service Failures

   sudo journalctl -u aitbc-node.service -f
   

4. Network Issues

   sudo netstat -tlnp | grep :8000
   

Get Help

# Check logs
./install.sh --logs

# Run diagnostics
./install.sh --diagnose

# Reset installation
./install.sh --reset

📚 Documentation

• Full Documentation
• Package Distribution - Package structure and installation
• macOS Packages - macOS CLI and Services
• API Reference
• Community Forum
• GitHub Issues

🤝 Contributing

Development Setup

git clone https://github.com/aitbc/aitbc.git
cd aitbc
./packages/github/install.sh --dev

Building Packages

./packages/github/build-all.sh

Testing

./packages/github/test.sh

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Debian packaging community
• Python packaging tools
• Systemd service standards
• Open source contributors

---

🚀 Ready to deploy AITBC CLI and Services on any system!