oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions 7 Packages Projects Releases Wiki Activity
Files
6f246ab5cc4dda304e1779de894ffab55096a45a
aitbc/docs/VIRTUAL_ENVIRONMENT.md
aitbc1 3352d63f36
All checks were successful
AITBC CLI Level 1 Commands Test / test-cli-level1 (push) Successful in 16s
Details
api-endpoint-tests / test-api-endpoints (push) Successful in 35s
Details
integration-tests / test-service-integration (push) Successful in 1m25s
Details
package-tests / test-python-packages (map[name:aitbc-agent-sdk path:packages/py/aitbc-agent-sdk python_version:3.13]) (push) Successful in 16s
Details
package-tests / test-python-packages (map[name:aitbc-cli path:. python_version:3.13]) (push) Successful in 14s
Details
package-tests / test-python-packages (map[name:aitbc-core path:packages/py/aitbc-core python_version:3.13]) (push) Successful in 13s
Details
package-tests / test-python-packages (map[name:aitbc-crypto path:packages/py/aitbc-crypto python_version:3.13]) (push) Successful in 10s
Details
package-tests / test-python-packages (map[name:aitbc-sdk path:packages/py/aitbc-sdk python_version:3.13]) (push) Successful in 12s
Details
package-tests / test-javascript-packages (map[name:aitbc-sdk node_version:24 path:packages/js/aitbc-sdk]) (push) Successful in 18s
Details
python-tests / test-specific (push) Has been skipped
Details
security-scanning / audit (push) Successful in 14s
Details
systemd-sync / sync-systemd (push) Successful in 4s
Details
package-tests / cross-language-compatibility (push) Successful in 2s
Details
package-tests / package-integration-tests (push) Successful in 3s
Details
Documentation Validation / validate-docs (push) Successful in 6m13s
Details
python-tests / test (push) Successful in 14s
Details
feat: major infrastructure refactoring and optimization 
## 🚀 Central Virtual Environment Implementation
- Created central venv at /opt/aitbc/venv for all services
- Updated 34+ systemd services to use central python interpreter
- Fixed PYTHONPATH configurations for proper module imports
- Created aitbc-env wrapper script for environment management

## 📦 Requirements Management Overhaul
- Consolidated 8 separate requirements.txt files into central requirements.txt
- Added web3>=6.11.0 for blockchain functionality
- Created automated requirements migrator tool (scripts/requirements_migrator.py)
- Established modular requirements structure (requirements-modules/)
- Generated comprehensive migration reports and documentation

## 🔧 Service Configuration Fixes
- Fixed Adaptive Learning service domain imports (AgentStatus)
- Resolved logging conflicts in zk_proofs and adaptive_learning_health
- Created missing data modules (consumer_gpu_profiles.py)
- Updated CLI to version 0.2.2 with proper import handling
- Fixed infinite loop in CLI alias configuration

## 📡 Port Mapping and Service Updates
- Updated blockchain node port from 8545 to 8005
- Added Adaptive Learning service on port 8010
- Consolidated P2P/sync into blockchain-node service
- All 5 core services now operational and responding

## 📚 Documentation Enhancements
- Updated SYSTEMD_SERVICES.md for Debian root usage (no sudo)
- Added comprehensive VIRTUAL_ENVIRONMENT.md guide
- Created REQUIREMENTS_MERGE_SUMMARY.md with migration details
- Updated RUNTIME_DIRECTORIES.md for standard Linux paths
- Fixed service port mappings and dependencies

## 🛠️ CLI Improvements
- Fixed import errors and version display (0.2.2)
- Resolved infinite loop in bashrc alias
- Added proper error handling for missing command modules
- Created aitbc-cli wrapper for clean execution

## ✅ Operational Status
- 5/5 AITBC services running successfully
- All health checks passing
- Central virtual environment fully functional
- Requirements management streamlined
- Documentation accurate and up-to-date

## 🎯 Technical Achievements
- Eliminated 7 redundant requirements.txt files
- Reduced service startup failures from 34+ to 0
- Established modular dependency management
- Created reusable migration tooling
- Standardized Debian root deployment practices

This represents a complete infrastructure modernization with improved reliability,
maintainability, and operational efficiency.
2026-03-29 11:52:37 +02:00

5.0 KiB
Raw Blame History

AITBC Central Virtual Environment Guide

Last Updated: 2026-03-29
Version: 3.2 (Virtual Environment Standardization)

Overview

AITBC now uses a central Python virtual environment to manage all dependencies consistently across services. This eliminates conflicts with system Python packages and provides a clean, isolated environment for all AITBC components.

🏗️ Virtual Environment Structure

/opt/aitbc/
├── venv/                    # Central virtual environment
│   ├── bin/                # Python executables and scripts
│   ├── lib/                # Installed packages
│   └── pyvenv.cfg          # Virtual environment configuration
├── requirements.txt        # Central dependency list
├── aitbc-env              # Environment wrapper script
└── apps/                   # AITBC applications

🚀 Quick Start

Activate Virtual Environment

# Use the environment wrapper (recommended)
/opt/aitbc/aitbc-env

# Or activate directly
source /opt/aitbc/venv/bin/activate

CLI Usage

# Start interactive shell with CLI access
/opt/aitbc/aitbc-env

# Use CLI commands directly
/opt/aitbc/aitbc-env aitbc --help

# Run Python scripts with venv
/opt/aitbc/aitbc-env python script.py

📦 Package Management

Dependencies Included

  • Web Framework: FastAPI, Uvicorn
  • Database: SQLAlchemy, SQLModel, Alembic
  • Security: Cryptography, PyNaCl
  • CLI Tools: Click, Rich, Typer
  • AI/ML: NumPy, Pandas, OpenCV
  • Monitoring: Prometheus Client, Structlog

Installing New Packages

# Activate environment first
/opt/aitbc/aitbc-env

# Install packages
pip install package-name

# Update requirements.txt
pip freeze > /opt/aitbc/requirements.txt

🔧 Service Integration

Updated Services

All major AITBC services now use the central virtual environment:

  • ✅ Wallet Service: /opt/aitbc/venv/bin/python
  • ✅ Exchange API: /opt/aitbc/venv/bin/python
  • ✅ Coordinator API: /opt/aitbc/venv/bin/python
  • ✅ Blockchain Node: /opt/aitbc/venv/bin/python

SystemD Configuration

Services automatically use the central venv via updated ExecStart paths:

[Service]
ExecStart=/opt/aitbc/venv/bin/python service_script.py

🛠️ Development Workflow

Development Environment

# Activate for development
/opt/aitbc/aitbc-env

# Run development servers
cd /opt/aitbc/apps/coordinator-api
uvicorn app.main:app --reload

# Run tests
pytest tests/

Environment Variables

The environment wrapper sets up:

PYTHONPATH=/opt/aitbc/packages/py/aitbc-sdk/src:/opt/aitbc/packages/py/aitbc-crypto/src
AITBC_VENV=/opt/aitbc/venv
PATH=/opt/aitbc/venv/bin:$PATH

🔍 Troubleshooting

Common Issues

Service Not Starting

# Check if venv exists
ls -la /opt/aitbc/venv/

# Check service status
sudo systemctl status aitbc-service-name

# Check logs
sudo journalctl -u aitbc-service-name -n 20

Missing Packages

# Install missing package
/opt/aitbc/aitbc-env pip install package-name

# Update all services
sudo systemctl restart aitbc-*

Import Errors

# Check PYTHONPATH
echo $PYTHONPATH

# Verify package installation
/opt/aitbc/aitbc-env python -c "import package_name"

Recreate Virtual Environment

# Backup current requirements
cp /opt/aitbc/requirements.txt /tmp/

# Remove and recreate
sudo rm -rf /opt/aitbc/venv
sudo python3 -m venv /opt/aitbc/venv
sudo chown -R root:root /opt/aitbc/venv

# Install packages
source /opt/aitbc/venv/bin/activate
pip install -r /opt/aitbc/requirements.txt

📋 Management Commands

Virtual Environment

# Check Python version
/opt/aitbc/aitbc-env python --version

# List installed packages
/opt/aitbc/aitbc-env pip list

# Check package details
/opt/aitbc/aitbc-env pip show package-name

Services

# Restart all services with venv
sudo systemctl restart aitbc-wallet aitbc-exchange-api

# Check service status
sudo systemctl status aitbc-*

# View service logs
sudo journalctl -u aitbc-service-name -f

🎯 Best Practices

  1. Always use the environment wrapper (/opt/aitbc/aitbc-env) for consistency
  2. Update requirements.txt when adding new packages
  3. Test services after dependency updates
  4. Monitor disk space - venv can grow with many packages
  5. Keep dependencies minimal - only install what's needed

🔄 Migration Notes

From System Python

  • No more --break-system-packages needed
  • Clean separation from OS packages
  • Consistent package versions across services

From Multiple Venvs

  • Single source of truth for dependencies
  • Easier maintenance and updates
  • Reduced disk usage

📚 Additional Resources

Next Steps: Use /opt/aitbc/aitbc-env for all AITBC development and operations.