diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md new file mode 100644 index 00000000..506ea7ec --- /dev/null +++ b/DEPLOYMENT.md @@ -0,0 +1,245 @@ +# Bzzz P2P Service Deployment Guide + +This document provides detailed instructions for deploying Bzzz as a production systemd service across multiple nodes. + +## Overview + +Bzzz has been successfully deployed as a systemd service across the deepblackcloud cluster, providing: +- Automatic startup on boot +- Automatic restart on failure +- Centralized logging via systemd journal +- Security sandboxing and resource limits +- Full mesh P2P network connectivity + +## Installation Steps + +### 1. Build Binary + +```bash +cd /home/tony/AI/projects/Bzzz +go build -o bzzz +``` + +### 2. Install Service + +```bash +# Install as systemd service (requires sudo) +sudo ./install-service.sh +``` + +The installation script: +- Makes the binary executable +- Copies service file to `/etc/systemd/system/bzzz.service` +- Reloads systemd daemon +- Enables auto-start on boot +- Starts the service immediately + +### 3. Verify Installation + +```bash +# Check service status +sudo systemctl status bzzz + +# View recent logs +sudo journalctl -u bzzz -n 20 + +# Follow live logs +sudo journalctl -u bzzz -f +``` + +## Current Deployment Status + +### Cluster Overview + +| Node | IP Address | Service Status | Node ID | Connected Peers | +|------|------------|----------------|---------|-----------------| +| **WALNUT** | 192.168.1.27 | ✅ Active | `12D3KooWEeVXdHkXtUp2ewzdqD56gDJCCuMGNAqoJrJ7CKaXHoUh` | 3 peers | +| **IRONWOOD** | 192.168.1.113 | ✅ Active | `12D3KooWFBSR...8QbiTa` | 3 peers | +| **ACACIA** | 192.168.1.xxx | ✅ Active | `12D3KooWE6c...Q9YSYt` | 3 peers | + +### Network Connectivity + +Full mesh P2P network established: + +``` + WALNUT (aXHoUh) + ↕ ↕ + ↙ ↘ +IRONWOOD ←→ ACACIA +(8QbiTa) (Q9YSYt) +``` + +- All nodes automatically discovered via mDNS +- Bidirectional connections established +- Capability broadcasts exchanged every 30 seconds +- Ready for distributed task coordination + +## Service Management + +### Basic Commands + +```bash +# Start service +sudo systemctl start bzzz + +# Stop service +sudo systemctl stop bzzz + +# Restart service +sudo systemctl restart bzzz + +# Check status +sudo systemctl status bzzz + +# Enable auto-start (already enabled) +sudo systemctl enable bzzz + +# Disable auto-start +sudo systemctl disable bzzz +``` + +### Logging + +```bash +# View recent logs +sudo journalctl -u bzzz -n 50 + +# Follow live logs +sudo journalctl -u bzzz -f + +# View logs from specific time +sudo journalctl -u bzzz --since "2025-07-12 19:00:00" + +# View logs with specific priority +sudo journalctl -u bzzz -p info +``` + +### Troubleshooting + +```bash +# Check if service is running +sudo systemctl is-active bzzz + +# Check if service is enabled +sudo systemctl is-enabled bzzz + +# View service configuration +sudo systemctl cat bzzz + +# Reload service configuration (after editing service file) +sudo systemctl daemon-reload +sudo systemctl restart bzzz +``` + +## Service Configuration + +### Service File Location + +`/etc/systemd/system/bzzz.service` + +### Key Configuration Settings + +- **Type**: `simple` - Standard foreground service +- **User/Group**: `tony:tony` - Runs as non-root user +- **Working Directory**: `/home/tony/AI/projects/Bzzz` +- **Restart Policy**: `always` with 10-second delay +- **Timeout**: 30-second graceful stop timeout + +### Security Settings + +- **NoNewPrivileges**: Prevents privilege escalation +- **PrivateTmp**: Isolated temporary directory +- **ProtectSystem**: Read-only system directories +- **ProtectHome**: Limited home directory access + +### Resource Limits + +- **File Descriptors**: 65,536 (for P2P connections) +- **Processes**: 4,096 (for Go runtime) + +## Network Configuration + +### Port Usage + +Bzzz automatically selects available ports for P2P communication: +- TCP ports in ephemeral range (32768-65535) +- IPv4 and IPv6 support +- Automatic port discovery and sharing via mDNS + +### Firewall Considerations + +For production deployments: +- Allow inbound TCP connections on used ports +- Allow UDP port 5353 for mDNS discovery +- Consider restricting to local network (192.168.1.0/24) + +### mDNS Discovery + +- Service Tag: `bzzz-peer-discovery` +- Network Scope: `192.168.1.0/24` +- Discovery Interval: Continuous background scanning + +## Monitoring and Maintenance + +### Health Checks + +```bash +# Check P2P connectivity +sudo journalctl -u bzzz | grep "Connected to" + +# Monitor capability broadcasts +sudo journalctl -u bzzz | grep "capability_broadcast" + +# Check for errors +sudo journalctl -u bzzz -p err +``` + +### Performance Monitoring + +```bash +# Resource usage +sudo systemctl status bzzz + +# Memory usage +ps aux | grep bzzz + +# Network connections +sudo netstat -tulpn | grep bzzz +``` + +### Maintenance Tasks + +1. **Log Rotation**: Systemd handles log rotation automatically +2. **Service Updates**: Stop service, replace binary, restart +3. **Configuration Changes**: Edit service file, reload systemd, restart + +## Uninstalling + +To remove the service: + +```bash +sudo ./uninstall-service.sh +``` + +This will: +- Stop the service if running +- Disable auto-start +- Remove service file +- Reload systemd daemon +- Reset any failed states + +Note: Binary and project files remain intact. + +## Deployment Timeline + +- **2025-07-12 19:46**: WALNUT service installed and started +- **2025-07-12 19:49**: IRONWOOD service installed and started +- **2025-07-12 19:49**: ACACIA service installed and started +- **2025-07-12 19:50**: Full mesh network established (3 nodes) + +## Next Steps + +1. **Integration**: Connect with Hive task coordination system +2. **Monitoring**: Set up centralized monitoring dashboard +3. **Scaling**: Add additional nodes to expand P2P mesh +4. **Task Execution**: Implement actual task processing workflows \ No newline at end of file diff --git a/README.md b/README.md index 26797438..779c40b6 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Bzzz + Antennae: Distributed P2P Task Coordination -Bzzz is a P2P task coordination system with the Antennae meta-discussion layer for collaborative AI reasoning. +Bzzz is a P2P task coordination system with the Antennae meta-discussion layer for collaborative AI reasoning. The system enables distributed AI agents to automatically discover each other, coordinate task execution, and engage in structured meta-discussions for improved collaboration. ## Architecture @@ -8,6 +8,7 @@ Bzzz is a P2P task coordination system with the Antennae meta-discussion layer f - **Task Coordination**: GitHub Issues as atomic task units - **Meta-Discussion**: Antennae layer for collaborative reasoning between agents - **Distributed Logging**: Hypercore-based tamper-proof audit trails +- **Service Deployment**: SystemD service for production deployment ## Components @@ -18,6 +19,82 @@ Bzzz is a P2P task coordination system with the Antennae meta-discussion layer f - `logging/` - Hypercore-based distributed logging - `cmd/` - Command-line interfaces +## Quick Start + +### Building from Source + +```bash +go build -o bzzz +``` + +### Running as Service + +Install Bzzz as a systemd service for production deployment: + +```bash +# Install service (requires sudo) +sudo ./install-service.sh + +# Check service status +sudo systemctl status bzzz + +# View live logs +sudo journalctl -u bzzz -f + +# Stop service +sudo systemctl stop bzzz + +# Uninstall service +sudo ./uninstall-service.sh +``` + +### Running Manually + +```bash +./bzzz +``` + +## Production Deployment + +### Service Management + +Bzzz is deployed as a systemd service across the cluster: + +- **Auto-start**: Service starts automatically on boot +- **Auto-restart**: Service restarts on failure with 10-second delay +- **Logging**: All output captured in systemd journal +- **Security**: Runs with limited privileges and filesystem access +- **Resource Limits**: Configured file descriptor and process limits + +### Cluster Status + +Currently deployed on: + +| Node | Service Status | Node ID | Connected Peers | +|------|----------------|---------|-----------------| +| **WALNUT** | ✅ Active | `12D3Koo...aXHoUh` | 3 peers | +| **IRONWOOD** | ✅ Active | `12D3Koo...8QbiTa` | 3 peers | +| **ACACIA** | ✅ Active | `12D3Koo...Q9YSYt` | 3 peers | + +### Network Topology + +Full mesh P2P network established: +- Automatic peer discovery via mDNS on `192.168.1.0/24` +- All nodes connected to all other nodes +- Capability broadcasts exchanged every 30 seconds +- Ready for distributed task coordination + +## Service Configuration + +The systemd service (`bzzz.service`) includes: + +- **Working Directory**: `/home/tony/AI/projects/Bzzz` +- **User/Group**: `tony:tony` +- **Restart Policy**: `always` with 10-second delay +- **Security**: NoNewPrivileges, PrivateTmp, ProtectSystem +- **Logging**: Output to systemd journal with `bzzz` identifier +- **Resource Limits**: 65536 file descriptors, 4096 processes + ## Development Status This project is being developed collaboratively across the deepblackcloud cluster: @@ -28,5 +105,13 @@ This project is being developed collaboratively across the deepblackcloud cluste ## Network Configuration - **Local Network**: 192.168.1.0/24 -- **mDNS Discovery**: Automatic peer discovery -- **Docker Deployment**: Host networking mode for P2P connectivity \ No newline at end of file +- **mDNS Discovery**: Automatic peer discovery with service tag `bzzz-peer-discovery` +- **PubSub Topics**: + - `bzzz/coordination/v1` - Task coordination messages + - `antennae/meta-discussion/v1` - Collaborative reasoning +- **Security**: Message signing and signature verification enabled + +## Related Projects + +- **[Hive](https://github.com/anthonyrawlins/hive)** - Multi-Agent Task Coordination System +- **[Antennae](https://github.com/anthonyrawlins/antennae)** - AI Collaborative Reasoning Protocol \ No newline at end of file diff --git a/bzzz.service b/bzzz.service new file mode 100644 index 00000000..dfba0b21 --- /dev/null +++ b/bzzz.service @@ -0,0 +1,40 @@ +[Unit] +Description=Bzzz P2P Task Coordination System +Documentation=https://github.com/anthonyrawlins/bzzz +After=network.target +Wants=network.target + +[Service] +Type=simple +User=tony +Group=tony +WorkingDirectory=/home/tony/AI/projects/Bzzz +ExecStart=/home/tony/AI/projects/Bzzz/bzzz +Restart=always +RestartSec=10 +KillMode=mixed +KillSignal=SIGTERM +TimeoutStopSec=30 + +# Environment variables +Environment=HOME=/home/tony +Environment=USER=tony + +# Logging +StandardOutput=journal +StandardError=journal +SyslogIdentifier=bzzz + +# Security settings +NoNewPrivileges=true +PrivateTmp=true +ProtectSystem=strict +ProtectHome=false +ReadWritePaths=/home/tony/AI/projects/Bzzz + +# Resource limits +LimitNOFILE=65536 +LimitNPROC=4096 + +[Install] +WantedBy=multi-user.target \ No newline at end of file diff --git a/install-service.sh b/install-service.sh new file mode 100755 index 00000000..64e19b22 --- /dev/null +++ b/install-service.sh @@ -0,0 +1,66 @@ +#!/bin/bash + +# Bzzz P2P Service Installation Script +# Installs Bzzz as a systemd service + +set -e + +echo "🐝 Installing Bzzz P2P Task Coordination Service..." + +# Check if running as root or with sudo +if [ "$EUID" -ne 0 ]; then + echo "❌ This script must be run as root or with sudo" + exit 1 +fi + +# Define paths +BZZZ_DIR="/home/tony/AI/projects/Bzzz" +SERVICE_FILE="$BZZZ_DIR/bzzz.service" +SYSTEMD_DIR="/etc/systemd/system" + +# Check if Bzzz binary exists +if [ ! -f "$BZZZ_DIR/bzzz" ]; then + echo "❌ Bzzz binary not found at $BZZZ_DIR/bzzz" + echo " Please build the binary first with: go build -o bzzz" + exit 1 +fi + +# Make binary executable +chmod +x "$BZZZ_DIR/bzzz" +echo "✅ Made Bzzz binary executable" + +# Copy service file to systemd directory +cp "$SERVICE_FILE" "$SYSTEMD_DIR/bzzz.service" +echo "✅ Copied service file to $SYSTEMD_DIR/bzzz.service" + +# Set proper permissions +chmod 644 "$SYSTEMD_DIR/bzzz.service" +echo "✅ Set service file permissions" + +# Reload systemd daemon +systemctl daemon-reload +echo "✅ Reloaded systemd daemon" + +# Enable service to start on boot +systemctl enable bzzz.service +echo "✅ Enabled Bzzz service for auto-start" + +# Start the service +systemctl start bzzz.service +echo "✅ Started Bzzz service" + +# Check service status +echo "" +echo "📊 Service Status:" +systemctl status bzzz.service --no-pager -l + +echo "" +echo "🎉 Bzzz P2P Task Coordination Service installed successfully!" +echo "" +echo "Commands:" +echo " sudo systemctl start bzzz - Start the service" +echo " sudo systemctl stop bzzz - Stop the service" +echo " sudo systemctl restart bzzz - Restart the service" +echo " sudo systemctl status bzzz - Check service status" +echo " sudo journalctl -u bzzz -f - Follow service logs" +echo " sudo systemctl disable bzzz - Disable auto-start" \ No newline at end of file diff --git a/uninstall-service.sh b/uninstall-service.sh new file mode 100755 index 00000000..930de9ba --- /dev/null +++ b/uninstall-service.sh @@ -0,0 +1,53 @@ +#!/bin/bash + +# Bzzz P2P Service Uninstallation Script +# Removes Bzzz systemd service + +set -e + +echo "🐝 Uninstalling Bzzz P2P Task Coordination Service..." + +# Check if running as root or with sudo +if [ "$EUID" -ne 0 ]; then + echo "❌ This script must be run as root or with sudo" + exit 1 +fi + +# Define paths +SYSTEMD_DIR="/etc/systemd/system" +SERVICE_FILE="$SYSTEMD_DIR/bzzz.service" + +# Check if service exists +if [ ! -f "$SERVICE_FILE" ]; then + echo "⚠️ Bzzz service not found at $SERVICE_FILE" + echo " Service may not be installed" + exit 0 +fi + +# Stop the service if running +if systemctl is-active --quiet bzzz.service; then + systemctl stop bzzz.service + echo "✅ Stopped Bzzz service" +fi + +# Disable the service +if systemctl is-enabled --quiet bzzz.service; then + systemctl disable bzzz.service + echo "✅ Disabled Bzzz service auto-start" +fi + +# Remove service file +rm -f "$SERVICE_FILE" +echo "✅ Removed service file" + +# Reload systemd daemon +systemctl daemon-reload +echo "✅ Reloaded systemd daemon" + +# Reset failed state if any +systemctl reset-failed bzzz.service 2>/dev/null || true + +echo "" +echo "🎉 Bzzz P2P Task Coordination Service uninstalled successfully!" +echo "" +echo "Note: The Bzzz binary and project files remain in /home/tony/AI/projects/Bzzz" \ No newline at end of file