tony/bzzz
1
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

Add production deployment documentation and systemd service support

Browse Source 
- Enhanced README.md with complete deployment instructions
- Added DEPLOYMENT.md with detailed service management guide
- Included systemd service configuration (bzzz.service)
- Added install-service.sh and uninstall-service.sh scripts
- Documented current cluster deployment status:
  * WALNUT: Active service with Node ID 12D3Koo...aXHoUh
  * IRONWOOD: Active service with Node ID 12D3Koo...8QbiTa
  * ACACIA: Active service with Node ID 12D3Koo...Q9YSYt
- Full mesh P2P network operational across all 3 nodes
- Auto-start, auto-restart, logging, and security configuration
- Service management commands and troubleshooting guide

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
anthonyrawlins
2025-07-12 19:52:03 +10:00
parent e8244a783b
commit 88d54c8408
5 changed files with 492 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

245
DEPLOYMENT.md Normal file
View File

@@ -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

91
README.md
View File

@@ -1,6 +1,6 @@
# Bzzz + Antennae: Distributed P2P Task Coordination # 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 ## 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 - **Task Coordination**: GitHub Issues as atomic task units
- **Meta-Discussion**: Antennae layer for collaborative reasoning between agents - **Meta-Discussion**: Antennae layer for collaborative reasoning between agents
- **Distributed Logging**: Hypercore-based tamper-proof audit trails - **Distributed Logging**: Hypercore-based tamper-proof audit trails
- **Service Deployment**: SystemD service for production deployment
## Components ## Components
@@ -18,6 +19,82 @@ Bzzz is a P2P task coordination system with the Antennae meta-discussion layer f
- `logging/` - Hypercore-based distributed logging - `logging/` - Hypercore-based distributed logging
- `cmd/` - Command-line interfaces - `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 ## Development Status
This project is being developed collaboratively across the deepblackcloud cluster: 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 ## Network Configuration
- **Local Network**: 192.168.1.0/24 - **Local Network**: 192.168.1.0/24
- **mDNS Discovery**: Automatic peer discovery - **mDNS Discovery**: Automatic peer discovery with service tag `bzzz-peer-discovery`
- **Docker Deployment**: Host networking mode for P2P connectivity - **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

40
bzzz.service Normal file
View File

@@ -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

66
install-service.sh Executable file
View File

@@ -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"

53
uninstall-service.sh Executable file
View File

@@ -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"