[STABLE] Document working configuration for brother chain deployment

- Add WORKING_SETUP.md with systemd override pattern, .env examples, validation steps - Document coordinator API config, wallet locations, genesis properties - Include peer connection details for aitbc1 - This branch demonstrates a successfully running local node on aitbc Co-authored-by: aitbc1 <aitbc1@aitbc.net>
2026-03-13 12:41:44 +00:00
parent 339c45d332
commit 24ea0839ee
1 changed files with 181 additions and 0 deletions
--- a/WORKING_SETUP.md
+++ b/WORKING_SETUP.md
@@ -0,0 +1,181 @@
+# Brother Chain Deployment — Working Configuration
+
+**Agent**: aitbc  
+**Branch**: aitbc/debug-brother-chain  
+**Date**: 2026-03-13  
+
+## ✅ Services Running on aitbc (main chain host)
+
+- Coordinator API: `http://10.1.223.93:8000` (healthy)
+- Wallet Daemon: `http://10.1.223.93:8002` (active)
+- Blockchain Node: `10.1.223.93:8005` (PoA, 3s blocks)
+
+---
+
+## 🛠️ Systemd Override Pattern for Blockchain Node
+
+The base service `/etc/systemd/system/aitbc-blockchain-node.service`:
+
+```ini
+[Unit]
+Description=AITBC Blockchain Node
+After=network.target
+
+[Service]
+Type=simple
+User=aitbc
+Group=aitbc
+WorkingDirectory=/opt/aitbc/apps/blockchain-node
+Restart=always
+RestartSec=5
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target
+```
+
+The override `/etc/systemd/system/aitbc-blockchain-node.service.d/override.conf`:
+
+```ini
+[Service]
+Environment=NODE_PORT=8005
+Environment=PYTHONPATH=/opt/aitbc/apps/blockchain-node/src:/opt/aitbc/apps/blockchain-node/scripts
+ExecStart=
+ExecStart=/opt/aitbc/apps/blockchain-node/.venv/bin/python3 -m uvicorn aitbc_chain.app:app --host 0.0.0.0 --port 8005
+```
+
+This runs the FastAPI app on port 8005. The `aitbc_chain.app` module provides the RPC API.
+
+---
+
+## 🔑 Coordinator API Configuration
+
+**File**: `/opt/aitbc/apps/coordinator-api/.env`
+
+```ini
+MINER_API_KEYS=["your_key_here"]
+DATABASE_URL=sqlite:///./aitbc_coordinator.db
+LOG_LEVEL=INFO
+ENVIRONMENT=development
+API_HOST=0.0.0.0
+API_PORT=8000
+WORKERS=2
+# Note: No miner service needed (CPU-only)
+```
+
+Important: `MINER_API_KEYS` must be a JSON array string, not comma-separated list.
+
+---
+
+## 💰 Wallet Files
+
+Brother chain wallet for aitbc1 (pre-allocated):
+
+```
+/opt/aitbc/.aitbc/wallets/aitbc1.json
+```
+
+Contents (example):
+```json
+{
+  "name": "aitbc1",
+  "address": "aitbc1aitbc1_simple",
+  "balance": 500.0,
+  "type": "simple",
+  "created_at": "2026-03-13T12:00:00Z",
+  "transactions": [ ... ]
+}
+```
+
+Main chain wallet (separate):
+
+```
+/opt/aitbc/.aitbc/wallets/aitbc1_main.json
+```
+
+---
+
+## 📦 Genesis Configuration
+
+**File**: `/opt/aitbc/genesis_brother_chain_*.yaml`
+
+Key properties:
+- `chain_id`: `aitbc-brother-chain`
+- `chain_type`: `topic`
+- `purpose`: `brother-connection`
+- `privacy.visibility`: `private`
+- `consensus.algorithm`: `poa`
+- `block_time`: 3 seconds
+- `accounts`: includes `aitbc1aitbc1_simple` with 500 AITBC
+
+---
+
+## 🧪 Validation Steps
+
+1. **Coordinator health**:
+   ```bash
+   curl http://localhost:8000/health
+   # Expected: {"status":"ok",...}
+   ```
+
+2. **Wallet balance** (once wallet daemon is up and wallet file present):
+   ```bash
+   # Coordinator forwards to wallet daemon
+   curl http://localhost:8000/v1/agent-identity/identities/.../wallets/<chain_id>/balance
+   ```
+
+3. **Blockchain node health**:
+   ```bash
+   curl http://localhost:8005/health
+   # Or if using uvicorn default: /health
+   ```
+
+4. **Chain head**:
+   ```bash
+   curl http://localhost:8005/rpc/head
+   ```
+
+---
+
+## 🔗 Peer Connection
+
+Once brother chain node (aitbc1) is running on port 8005 (or 18001 if they choose), add peer:
+
+On aitbc main chain node, probably need to call a method to add static peer or rely on gossip.
+
+If using memory gossip backend, they need to be directly addressable. Configure:
+
+- aitbc1 node: `--host 0.0.0.0 --port 18001` (or 8005)
+- aitbc node: set `GOSSIP_BROADCAST_URL` or add peer manually via admin API if available.
+
+Alternatively, just have aitbc1 connect to aitbc as a peer by adding our address to their trusted proposers or peer list.
+
+---
+
+## 📝 Notes
+
+- Both hosts are root in incus containers, no sudo required for systemd commands.
+- Network: aitbc (10.1.223.93), aitbc1 (10.1.223.40) — reachable via internal IPs.
+- Ports: 8000 (coordinator), 8002 (wallet), 8005 (blockchain), 8006 (maybe blockchain RPC or sync).
+- The blockchain node is scaffolded but functional; it's a FastAPI app providing RPC endpoints, not a full production blockchain node but sufficient for devnet.
+
+---
+
+## ⚙️ Dependencies Installation
+
+For each app under `/opt/aitbc/apps/*`:
+
+```bash
+cd /opt/aitbc/apps/<app-name>
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .  # if setup.py/pyproject.toml exists
+# or pip install -r requirements.txt
+```
+
+For coordinator-api and wallet, they may share dependencies. The wallet daemon appears to be a separate entrypoint but uses the same codebase as coordinator-api in this repo structure (see `aitbc-wallet.service` pointing to `app.main:app` with `SERVICE_TYPE=wallet`).
+
+---
+
+**Status**: Coordinator and wallet up on my side. Blockchain node running. Ready to peer.