161 lines
5.3 KiB
Markdown
161 lines
5.3 KiB
Markdown
# Environment
|
|
|
|
This document describes the current development environment configuration, including services, ports, environment variables, and setup steps.
|
|
|
|
## Host Information
|
|
|
|
**Primary Host**: `aitbc1`
|
|
- OS: Linux (6.11.10-amd64)
|
|
- Workspace: `/root/.openclaw/workspace`
|
|
- Python: 3.10+ (node v22.22.1 also installed for tooling)
|
|
- Shell: zsh
|
|
- Timezone: UTC
|
|
|
|
**Sibling Host**: `aitbc`
|
|
- Remote machine (details may differ)
|
|
- Communication: via Gitea API, SSH, P2P
|
|
|
|
## Repository Layout
|
|
|
|
```
|
|
/root/.openclaw/workspace/
|
|
├── ai-memory/ # Structured memory (canonical)
|
|
│ ├── daily/
|
|
│ ├── architecture/
|
|
│ ├── decisions/
|
|
│ ├── failures/
|
|
│ ├── knowledge/
|
|
│ └── agents/
|
|
├── memory/ # Legacy per-agent hourly logs (deprecated)
|
|
│ ├── aitbc/
|
|
│ ├── aitbc1/
|
|
│ └── archive/
|
|
├── MEMORY.md # Curated long-term notes (to be migrated)
|
|
├── packages/py/ # Python packages (aitbc-*)
|
|
├── apps/
|
|
│ ├── coordinator-api/
|
|
│ └── blockchain-node/
|
|
├── cli/
|
|
│ └── aitbc_cli/
|
|
├── scripts/
|
|
├── AGENTS.md
|
|
├── SOUL.md
|
|
└── README.md
|
|
```
|
|
|
|
## Services & Ports
|
|
|
|
| Service | Path | Port | Protocol | Status (typically) |
|
|
|--------------------|------------------------------|------|----------|--------------------|
|
|
| Coordinator API | `apps/coordinator-api` | 8000 | HTTP | Running |
|
|
| Blockchain RPC | `apps/blockchain-node` | 8006 | HTTP | Running |
|
|
| Blockchain P2P | `apps/blockchain-node` | 8005 | WebSocket| Running |
|
|
| Wallet Daemon | `apps/blockchain-node` | 8015 | HTTP | Running |
|
|
| AI Provider | Launched via CLI `ai serve` | 8008 | HTTP | On-demand |
|
|
| Redis | System service | 6379 | TCP | Running (dev) |
|
|
|
|
## Environment Variables
|
|
|
|
Common variables used:
|
|
|
|
- `LOG_LEVEL`: Logging level (default `INFO`). Set to `DEBUG` for verbose.
|
|
- `DATABASE_URL`: Database connection string. Example: `sqlite+aiosqlite:///data/coordinator.db`
|
|
- `REDIS_URL`: Redis connection. Default: `redis://localhost`
|
|
- `HOST`: Service host (usually `0.0.0.0` to bind all)
|
|
- `PORT`: Service port (overrides default)
|
|
- `GITEA_TOKEN`: API token for Gitea (automation scripts). Not in repo.
|
|
|
|
Services typically read these from environment or use defaults.
|
|
|
|
## Virtual Environments
|
|
|
|
Each package/service may have its own virtualenv under `venv/` or use a central one.
|
|
|
|
- CLI venv: `/opt/aitbc/cli/cli_venv` (or `/opt/aitbc/cli/venv`)
|
|
- Coordinator venv: (maybe) `apps/coordinator-api/venv`
|
|
- Blockchain node venv: `apps/blockchain-node/venv` or system Python
|
|
|
|
**Important**: Activate the correct venv before running commands:
|
|
```bash
|
|
source /opt/aitbc/cli/cli_venv/bin/activate
|
|
aitbc --help
|
|
```
|
|
|
|
## Setup Steps (New Developer)
|
|
|
|
1. Clone repository to workspace.
|
|
2. Install **Poetry** (if not installed).
|
|
3. Install dependencies for each package:
|
|
```bash
|
|
cd packages/py/aitbc-core && poetry install
|
|
cd ../aitbc-crypto && poetry install
|
|
cd ../aitbc-sdk && poetry install
|
|
cd ../aitbc-agent-sdk && poetry install
|
|
```
|
|
4. Install CLI dependencies (either via Poetry in `cli/` or use venv):
|
|
```bash
|
|
cd cli
|
|
python -m venv venv
|
|
source venv/bin/activate
|
|
pip install -e .
|
|
```
|
|
5. Install service dependencies for `coordinator-api` and `blockchain-node` similarly.
|
|
6. Start Redis: `sudo systemctl start redis` or `redis-server`.
|
|
7. Initialize and start coordinator DB:
|
|
```bash
|
|
cd apps/coordinator-api
|
|
source venv/bin/activate
|
|
python -m app.init_db
|
|
uvicorn app.main:app --reload --port 8000
|
|
```
|
|
8. Start blockchain devnet:
|
|
```bash
|
|
cd apps/blockchain-node
|
|
source venv/bin/activate
|
|
./scripts/devnet_up.sh
|
|
```
|
|
9. Verify services:
|
|
```bash
|
|
curl http://localhost:8000/health
|
|
curl http://localhost:8006/health
|
|
```
|
|
10. Configure Gitea token for automation: `export GITEA_TOKEN=...` in shell profile or cron environment.
|
|
|
|
## Testing
|
|
|
|
- Run package tests with `pytest` inside the package directory or via `poetry run pytest`.
|
|
- CLI tests: `aitbc <command>` after activating CLI venv.
|
|
- Integration tests may require all services running.
|
|
|
|
## Known Issues
|
|
|
|
- Starlette must be pinned `<0.38`.
|
|
- Docker Compose command name varies (`docker compose` vs `docker-compose`).
|
|
- Absolute paths in some old scripts; replaced with relative.
|
|
- Redis is dev-only; not hardened for internet.
|
|
|
|
## Monitoring
|
|
|
|
- Health endpoints:
|
|
- Coordinator: `GET /health` → `{"status":"ok"}`
|
|
- Blockchain: `GET /health` or `/status`
|
|
- Wallet: `GET /wallet/balance?addr=...`
|
|
- Logs: Check stdout/stderr of services, or systemd journal if installed as services.
|
|
|
|
## Troubleshooting
|
|
|
|
- Port in use: `lsof -i:<port>` to find culprit.
|
|
- Database locked: ensure only one process writes; use `IF NOT EXISTS` for idempotent init.
|
|
- Import errors: verify `PYTHONPATH` and virtualenv activation.
|
|
- Redis connection refused: start Redis server (`systemctl start redis`).
|
|
|
|
## Future Improvements
|
|
|
|
- Production P2P without Redis.
|
|
- TLS for all services.
|
|
- Centralized configuration management (e.g., TOML file).
|
|
- Docker Compose for whole stack (robustified).
|
|
|
|
---
|
|
|
|
*Update this file whenever environment configuration changes.* |