From dc2733253895c99b75341ea0c061ac5dae1f0a7d Mon Sep 17 00:00:00 2001 From: aitbc Date: Sat, 9 May 2026 19:53:11 +0200 Subject: [PATCH] docs: update configuration references from production.env to blockchain.env - Update documentation to reflect consolidation of production.env into blockchain.env - Change file references in configuration management, agent training, and release docs - Update troubleshooting and setup instructions to use blockchain.env - Remove references to deprecated 3-file structure (blockchain.env, node.env, production.env) - Document completed consolidation benefits and migration steps --- .../skills/aitbc-configuration-management.md | 35 +++++++++++++------ .../stage10_failure_recovery.json | 4 +-- .../adding_gitea_runner_as_third_node.md | 14 ++++---- docs/releases/RELEASE_v0.2.5.md | 8 ++--- docs/releases/RELEASE_v0.3.2.md | 3 +- docs/skills/aitbc-node-coordination.md | 2 +- 6 files changed, 40 insertions(+), 26 deletions(-) diff --git a/.windsurf/skills/aitbc-configuration-management.md b/.windsurf/skills/aitbc-configuration-management.md index 288581ff..fb868b68 100644 --- a/.windsurf/skills/aitbc-configuration-management.md +++ b/.windsurf/skills/aitbc-configuration-management.md @@ -8,10 +8,10 @@ Specialized skill for managing `/etc/aitbc/` configuration files across multi-no ### File Organization ``` /etc/aitbc/ -├── blockchain.env # Shared blockchain configuration (chains, RPC, sync) +├── blockchain.env # Shared blockchain and production configuration ├── node.env # Node-specific configuration (P2P, proposer ID) -├── production.env # Production environment variables ├── credentials/ # Keystore and secrets +├── production.env.backup # Backup of consolidated production.env └── .env.backup # Legacy configuration backup ``` @@ -23,8 +23,11 @@ Specialized skill for managing `/etc/aitbc/` configuration files across multi-no - RPC binding configuration - Sync configuration (SYNC_SOURCE_HOST, SYNC_LEADER_HOST) - Block production settings -- Database and Redis URLs +- Database and Redis URLs (PostgreSQL, Redis) - API and service port bindings +- Production environment variables (NODE_ENV, LOG_LEVEL) +- Security keys (SECRET_KEY, JWT_SECRET, BLOCKCHAIN_API_KEY) +- Monitoring configuration (PROMETHEUS_PORT, GRAFANA_PORT) **node.env** - Node-specific identity (NODE_ID, p2p_node_id) @@ -33,14 +36,6 @@ Specialized skill for managing `/etc/aitbc/` configuration files across multi-no - Trusted proposers list - Node-specific host bindings -**production.env** -- Production environment variables -- NODE_ENV, LOG_LEVEL -- Database and Redis URLs -- Security keys (SECRET_KEY, JWT_SECRET) -- Service port configurations -- Monitoring endpoints - ## Multi-Node Configuration ### Chain Hub Architecture @@ -152,6 +147,24 @@ grep -r "EnvironmentFile=/etc/aitbc" /etc/systemd/system/aitbc-*.service ## Migration Procedures +### Consolidation from 3 Files to 2 Files + +**Completed consolidation (2026-05-09):** +- Merged production.env into blockchain.env +- Removed duplicate DATABASE_URL and REDIS_URL (kept PostgreSQL and localhost) +- Added production environment variables to blockchain.env +- Added security keys to blockchain.env +- Added monitoring configuration to blockchain.env +- Deleted production.env (backed up to production.env.backup) +- Updated all nodes (aitbc, aitbc1, gitea-runner) +- Restarted services on all nodes + +**Benefits:** +- Simpler configuration structure (2 files instead of 3) +- No overlapping variables +- Clear separation: blockchain.env (shared) + node.env (node-specific) +- Single source of truth for production settings + ### Legacy .env → blockchain.env Migration **Completed migration steps:** diff --git a/docs/agent-training/stage10_failure_recovery.json b/docs/agent-training/stage10_failure_recovery.json index 008c9db3..8590e55a 100644 --- a/docs/agent-training/stage10_failure_recovery.json +++ b/docs/agent-training/stage10_failure_recovery.json @@ -333,7 +333,7 @@ { "operation": "configuration_backup", "parameters": { - "config_files": ["/etc/aitbc/.env", "/etc/aitbc/node.env"], + "config_files": ["/etc/aitbc/blockchain.env", "/etc/aitbc/node.env"], "backup_location": "/opt/aitbc/backups/config" }, "expected_result": { @@ -345,7 +345,7 @@ }, "examples": [ { - "command": "tar -czf /opt/aitbc/backups/config/aitbc-config-backup.tar.gz /etc/aitbc/.env /etc/aitbc/node.env", + "command": "tar -czf /opt/aitbc/backups/config/aitbc-config-backup.tar.gz /etc/aitbc/blockchain.env /etc/aitbc/node.env", "description": "Backup configuration files" }, { diff --git a/docs/blockchain/adding_gitea_runner_as_third_node.md b/docs/blockchain/adding_gitea_runner_as_third_node.md index 75084b70..46820ac8 100644 --- a/docs/blockchain/adding_gitea_runner_as_third_node.md +++ b/docs/blockchain/adding_gitea_runner_as_third_node.md @@ -51,7 +51,7 @@ trusted_proposers= ### Step 2: Configure Shared Environment on gitea-runner -**File**: `/etc/aitbc/.env` +**File**: `/etc/aitbc/blockchain.env` ```bash # AITBC Environment Configuration @@ -134,7 +134,7 @@ p2p_bind_port=7070 ### Step 6: Update Gossip Backend Configuration -**File**: `/etc/aitbc/.env` (all nodes) +**File**: `/etc/aitbc/blockchain.env` (all nodes) Updated to use shared Redis instance for gossip: @@ -220,7 +220,7 @@ This makes gitea-runner a follower node that only receives blocks from the netwo **Symptom**: gitea-runner blockchain height remained at 25 despite copying database -**Cause**: `DATABASE_URL` in `.env` was set to `sqlite:////var/lib/aitbc/aitbc.db` but the config uses `db_path` which defaults to `/var/lib/aitbc/data/chain.db` +**Cause**: `DATABASE_URL` in `blockchain.env` was set to `sqlite:////var/lib/aitbc/aitbc.db` but the config uses `db_path` which defaults to `/var/lib/aitbc/data/chain.db` **Resolution**: Updated `DATABASE_URL` to match the actual database location: ```bash @@ -233,7 +233,7 @@ DATABASE_URL=sqlite:////var/lib/aitbc/data/chain.db **Cause**: The blockchain node uses `supported_chains` (default: "ait-devnet") to determine which chains to propose blocks on, not just `CHAIN_ID` -**Resolution**: Explicitly set `supported_chains` in `.env`: +**Resolution**: Explicitly set `supported_chains` in `blockchain.env`: ```bash supported_chains=ait-devnet ``` @@ -308,13 +308,13 @@ ssh gitea-runner "journalctl -u aitbc-blockchain-node.service -n 30 --no-pager" 1. **supported_chains is Critical**: The blockchain node uses `supported_chains` to determine which chains to propose blocks on. This must be set explicitly, not just `CHAIN_ID`. -2. **Database Location Matters**: The `DATABASE_URL` in `.env` must match the actual database location used by the config (`db_path` defaults to `/var/lib/aitbc/data/chain.db`). +2. **Database Location Matters**: The `DATABASE_URL` in `blockchain.env` must match the actual database location used by the config (`db_path` defaults to `/var/lib/aitbc/data/chain.db`). 3. **Proposer ID Conflicts**: All nodes with the same `proposer_id` will propose blocks simultaneously, causing forks. Disable block production on follower nodes. 4. **P2P Bind Configuration**: Missing `p2p_bind_host` and `p2p_bind_port` causes P2P service failures. These must be set in `node.env`. -5. **Environment Variable Loading**: Systemd services load environment variables from `EnvironmentFile` directives. Verify that the correct files are being loaded (`/etc/aitbc/.env` and `/etc/aitbc/node.env`). +5. **Environment Variable Loading**: Systemd services load environment variables from `EnvironmentFile` directives. Verify that the correct files are being loaded (`/etc/aitbc/blockchain.env` and `/etc/aitbc/node.env`). ## Recommendations @@ -345,7 +345,7 @@ ssh gitea-runner "journalctl -u aitbc-blockchain-node.service -n 30 --no-pager" - [Multi-Node Blockchain Setup](../../.windsurf/workflows/multi-node-blockchain-setup.md) ### Configuration Files -- `/etc/aitbc/.env` (shared environment) +- `/etc/aitbc/blockchain.env` (shared environment) - `/etc/aitbc/node.env` (node-specific environment) - `/etc/systemd/system/aitbc-blockchain-node.service` - `/etc/systemd/system/aitbc-blockchain-p2p.service` diff --git a/docs/releases/RELEASE_v0.2.5.md b/docs/releases/RELEASE_v0.2.5.md index 86a5aab3..23806462 100644 --- a/docs/releases/RELEASE_v0.2.5.md +++ b/docs/releases/RELEASE_v0.2.5.md @@ -36,7 +36,7 @@ AITBC v0.3.0 marks the **100% completion** of the entire project with all 9 majo - **Single Marketplace Service**: GPU functionality unified into `aitbc-marketplace.service` - **Service Consolidation**: Duplicate GPU service elimination - **Path Corrections**: All services using `/opt/aitbc/services` -- **Environment Consolidation**: `/etc/aitbc/production.env` +- **Environment Consolidation**: `/etc/aitbc/blockchain.env` (consolidated with production settings) - **Blockchain Service**: Functionality restored and operational ### **🔐 Basic Security (100%)** @@ -271,8 +271,8 @@ cd apps/agent-coordinator pip install -r requirements.txt # 4. Configure environment -cp /etc/aitbc/production.env.example /etc/aitbc/production.env -# Edit production.env with your settings +cp /etc/aitbc/blockchain.env.example /etc/aitbc/blockchain.env +# Edit blockchain.env with your settings # 5. Start services systemctl enable aitbc-agent-coordinator.service @@ -378,7 +378,7 @@ curl http://localhost:9001/health ### **🔧 Troubleshooting** - **Service Issues**: Check `systemctl status aitbc-agent-coordinator.service` -- **Authentication**: Verify JWT configuration in production.env +- **Authentication**: Verify JWT configuration in blockchain.env - **Monitoring**: Check Prometheus metrics endpoint - **Type Errors**: Run MyPy checking for detailed error reports diff --git a/docs/releases/RELEASE_v0.3.2.md b/docs/releases/RELEASE_v0.3.2.md index d879f82a..d85b8e55 100644 --- a/docs/releases/RELEASE_v0.3.2.md +++ b/docs/releases/RELEASE_v0.3.2.md @@ -120,9 +120,10 @@ This release focuses on resolving pytest import conflicts through test file nami ### ✅ **Environment Configuration Unification** - **Unified environment files**: Split global (.env) from node-specific (node.env) -- **Removed redundant files**: Removed production.env and blockchain.env +- **Removed redundant files**: Removed production.env (consolidated into blockchain.env) - **Moved hardcoded variables**: Moved from systemd services to environment files - **Benefits**: Single source of truth for configuration +- **Current structure**: blockchain.env (shared + production) + node.env (node-specific) ## 🔧 Systemd Service Improvements diff --git a/docs/skills/aitbc-node-coordination.md b/docs/skills/aitbc-node-coordination.md index 6c9c5c8c..778d699d 100644 --- a/docs/skills/aitbc-node-coordination.md +++ b/docs/skills/aitbc-node-coordination.md @@ -16,7 +16,7 @@ Coordinate cross-node operations, synchronize blockchain state, and manage inter - SSH access configured between genesis (aitbc) and follower (aitbc1) with key-based authentication - Blockchain nodes operational on both nodes via systemd services - P2P mesh network active on port 7070 with peer configuration -- Unique node IDs configured (proposer_id and p2p_node_id in `/etc/aitbc/.env` and `/etc/aitbc/node.env`) +- Unique node IDs configured (proposer_id and p2p_node_id in `/etc/aitbc/node.env`) - Git synchronization configured between nodes at `/opt/aitbc/.git` ## Operations