feat(deploy): add Gitea deployment templates, installer, and CI/CD workflow
This commit is contained in:
@@ -0,0 +1,52 @@
|
||||
# 🚀 Multi-Agent Mux (MAM) Deployment & Gitea Integration
|
||||
|
||||
This directory contains packaging templates and installation scripts to deploy the **Multi-Agent Mux** framework into workspaces hosted on **Gitea** (or GitHub).
|
||||
|
||||
---
|
||||
|
||||
## 📁 Deployment Directory Structure
|
||||
|
||||
* **`install.sh`**: A self-contained, idempotent shell installer that checks system requirements (`tmux`, `python3`, `pip3`), detects NFS/network filesystem mounts, sets up a local python virtual environment (`.venv`), and initializes environment configuration (`.env`).
|
||||
* **`plugin.json`**: Metadata declaration file to register MAM as an installable plugin for AI Agent coding platforms (such as Claude Code, Antigravity, or other TUI clients).
|
||||
* **`gitea-ci.yml`**: CI/CD pipeline definition template for Gitea Actions (running ShellCheck linting on bash scripts, validation on python scripts, and compilation tests).
|
||||
|
||||
---
|
||||
|
||||
## 📦 How to Install and Deploy
|
||||
|
||||
### 1. Simple One-Liner Installation (from Gitea repository)
|
||||
Once you push this repository to your Gitea instance, users can install it in their local workspace directory by running:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://<your-gitea-domain>/<username>/multi-agent-mux/raw/branch/main/deploy/install.sh | bash
|
||||
```
|
||||
|
||||
Alternatively, if they have cloned the repository, they can execute:
|
||||
```bash
|
||||
bash deploy/install.sh
|
||||
```
|
||||
|
||||
### 2. Registering as a Workspace Plugin
|
||||
To register these skills globally or for a specific workspace:
|
||||
* **Workspace Level**: Copy the `.agents/` folder into your project root.
|
||||
* **Global Level (Gemini/Antigravity)**: Register the plugin path in your global config file at `~/.gemini/config/skills.json`:
|
||||
```json
|
||||
{
|
||||
"entries": [
|
||||
{ "path": "/absolute/path/to/multi-agent-mux/.agents/skills" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Gitea Actions CI/CD Setup
|
||||
|
||||
To automate testing and script linting on your Gitea repository:
|
||||
1. Ensure Gitea Actions is enabled on your Gitea instance.
|
||||
2. Copy the Gitea CI workflow to your workspace's workflow folder:
|
||||
```bash
|
||||
mkdir -p .gitea/workflows
|
||||
cp deploy/gitea-ci.yml .gitea/workflows/ci.yml
|
||||
```
|
||||
3. Commit and push to your Gitea repository. The pipeline will validate shell syntax and python file compilation on every push to `main` and pull requests.
|
||||
@@ -0,0 +1,70 @@
|
||||
# ==============================================================================
|
||||
# Gitea Actions CI/CD Workflow Template
|
||||
# ==============================================================================
|
||||
# Place this file in '.gitea/workflows/ci.yml' or use it directly in Gitea's CI.
|
||||
# It automatically validates shell scripts and checks Python formatting/syntax.
|
||||
# ==============================================================================
|
||||
name: Multi-Agent Mux CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ main, dev ]
|
||||
pull_request:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
lint-shell:
|
||||
name: Lint Shell Scripts
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout Code
|
||||
uses: actions/checkout@v3
|
||||
|
||||
- name: Install ShellCheck
|
||||
run: |
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y shellcheck
|
||||
|
||||
- name: Run ShellCheck
|
||||
run: |
|
||||
echo "🔍 Linting shell scripts..."
|
||||
shellcheck .agents/skills/lib.sh
|
||||
shellcheck .agents/skills/multi-agent-mux-create/scripts/create_session.sh
|
||||
shellcheck .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh
|
||||
shellcheck .agents/skills/multi-agent-mux-monitor/scripts/reconcile.sh
|
||||
shellcheck deploy/install.sh
|
||||
echo "✅ ShellCheck completed successfully."
|
||||
|
||||
lint-python:
|
||||
name: Lint Python Backplane
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout Code
|
||||
uses: actions/checkout@v3
|
||||
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: '3.10'
|
||||
cache: 'pip'
|
||||
|
||||
- name: Install Dependencies
|
||||
run: |
|
||||
python -m pip install --upgrade pip
|
||||
pip install flake8 pylint
|
||||
if [ -f .agents/skills/multi-agent-mux-delegate-job/requirements.txt ]; then
|
||||
pip install -r .agents/skills/multi-agent-mux-delegate-job/requirements.txt
|
||||
fi
|
||||
|
||||
- name: Run Flake8 (Syntax/Error Check)
|
||||
run: |
|
||||
echo "🔍 Checking Python syntax with flake8..."
|
||||
flake8 .agents/skills/multi-agent-mux-delegate-job/scripts/ --count --select=E9,F63,F7,F82 --show-source --statistics
|
||||
# exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
|
||||
flake8 .agents/skills/multi-agent-mux-delegate-job/scripts/ --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
|
||||
|
||||
- name: Run Python Syntax Check (Compile test)
|
||||
run: |
|
||||
echo "🔍 Verifying Python file compilation..."
|
||||
python -m py_compile .agents/skills/multi-agent-mux-delegate-job/scripts/*.py
|
||||
echo "✅ All Python files compiled successfully."
|
||||
@@ -0,0 +1,125 @@
|
||||
#!/usr/bin/env bash
|
||||
# ==============================================================================
|
||||
# install.sh — Multi-Agent Mux (MAM) Orchestration Installer
|
||||
# ==============================================================================
|
||||
# Idempotent, robust installer to bootstrap MAM orchestration skills
|
||||
# and Python backplane dependencies on any local workspace.
|
||||
# ==============================================================================
|
||||
set -euo pipefail
|
||||
|
||||
# --- Configuration & Defaults ---
|
||||
TARGET_DIR="${1:-$(pwd)}"
|
||||
VENV_NAME=".venv"
|
||||
MIN_PYTHON_VERSION="3.9"
|
||||
|
||||
echo "===================================================================="
|
||||
echo "⚡ Starting Multi-Agent Mux (MAM) Installation"
|
||||
echo "📂 Target Workspace: $TARGET_DIR"
|
||||
echo "===================================================================="
|
||||
|
||||
# --- 1. System Requirements Validation ---
|
||||
echo "🔍 Checking system dependencies..."
|
||||
|
||||
check_cmd() {
|
||||
local cmd="$1"
|
||||
if ! command -v "$cmd" &>/dev/null; then
|
||||
echo "❌ Error: '$cmd' is not installed. Please install it first." >&2
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
check_cmd tmux
|
||||
check_cmd python3
|
||||
check_cmd pip3
|
||||
|
||||
# Verify Python Version
|
||||
PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
|
||||
if python3 -c "import sys; exit(0 if sys.version_info >= (3, 9) else 1)"; then
|
||||
echo "✅ Python $PYTHON_VERSION detected."
|
||||
else
|
||||
echo "❌ Error: Python version must be $MIN_PYTHON_VERSION or higher. Detected: $PYTHON_VERSION" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# --- 2. Workspace Setup ---
|
||||
cd "$TARGET_DIR"
|
||||
echo "📂 Ensuring metadata directory structure (.mam/)..."
|
||||
mkdir -p .mam/jobs .mam/delegate_job_logs
|
||||
|
||||
# File permission lockdown on database directory
|
||||
chmod 0700 .mam
|
||||
|
||||
# --- 3. Check Network File System (NFS) Warnings ---
|
||||
echo "💾 Detecting file system mount type..."
|
||||
if command -v df &>/dev/null && command -v mount &>/dev/null; then
|
||||
MOUNTPOINT="$(df --output=target . 2>/dev/null | tail -1 || echo "")"
|
||||
if [ -n "$MOUNTPOINT" ]; then
|
||||
if mount | grep -q "$MOUNTPOINT.*nfs\|$MOUNTPOINT.*cifs\|$MOUNTPOINT.*fuse.sshfs"; then
|
||||
echo "⚠️ WARNING: Target directory is on a network filesystem (NFS/CIFS/SSHFS)."
|
||||
echo " File locks (fcntl.flock) are UNRELIABLE on network storage."
|
||||
echo " The sqlite3 registry will fall back to 'DELETE' journaling instead of WAL."
|
||||
else
|
||||
echo "✅ File system supports WAL (Local storage detected)."
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# --- 4. Python Virtual Environment Setup ---
|
||||
echo "🐍 Bootstrapping Python virtual environment (.venv)..."
|
||||
if [ ! -d "$VENV_NAME" ]; then
|
||||
python3 -m venv "$VENV_NAME"
|
||||
echo "✅ Virtual environment created."
|
||||
else
|
||||
echo "ℹ️ Virtual environment (.venv) already exists. Skipping creation."
|
||||
fi
|
||||
|
||||
# Activate virtual environment
|
||||
# shellcheck disable=SC1091
|
||||
source "$VENV_NAME"/bin/activate
|
||||
|
||||
# Install requirements
|
||||
REQ_FILE=".agents/skills/multi-agent-mux-delegate-job/requirements.txt"
|
||||
if [ -f "$REQ_FILE" ]; then
|
||||
echo "📦 Installing backplane dependencies from $REQ_FILE..."
|
||||
pip install --upgrade pip
|
||||
pip install -r "$REQ_FILE"
|
||||
echo "✅ Dependencies installed successfully."
|
||||
else
|
||||
echo "⚠️ WARNING: Could not find requirements file: $REQ_FILE"
|
||||
echo " Installing default packages (paho-mqtt, pyyaml) manually..."
|
||||
pip install --upgrade pip
|
||||
pip install "paho-mqtt>=2.0.0" pyyaml
|
||||
fi
|
||||
|
||||
# --- 5. Generate Environment Template ---
|
||||
ENV_FILE=".env"
|
||||
ENV_EXAMPLE=".env.example"
|
||||
if [ ! -f "$ENV_FILE" ]; then
|
||||
if [ -f "$ENV_EXAMPLE" ]; then
|
||||
echo "📝 Creating configuration from $ENV_EXAMPLE..."
|
||||
cp "$ENV_EXAMPLE" "$ENV_FILE"
|
||||
chmod 0600 "$ENV_FILE"
|
||||
else
|
||||
echo "📝 Creating default $ENV_FILE..."
|
||||
cat <<EOF > "$ENV_FILE"
|
||||
# ==============================================================================
|
||||
# Multi-Agent Mux (MAM) Environment Settings
|
||||
# ==============================================================================
|
||||
MQTT_BROKER=broker.hivemq.com
|
||||
MQTT_PORT=1883
|
||||
MQTT_TLS=0
|
||||
MQTT_CLIENT_ID_PREFIX=mam-agent
|
||||
TMUX_SERVER_NAME=default
|
||||
EOF
|
||||
chmod 0600 "$ENV_FILE"
|
||||
fi
|
||||
echo "✅ Config file .env initialized with chmod 0600."
|
||||
else
|
||||
echo "ℹ️ $ENV_FILE already exists. Skipping config override."
|
||||
fi
|
||||
|
||||
echo "===================================================================="
|
||||
echo "🎉 Installation complete!"
|
||||
echo "✨ You can now run the status or monitor skills."
|
||||
echo "💡 Hint: Try executing: .venv/bin/python .agents/skills/multi-agent-mux-delegate-job/scripts/registry.py list"
|
||||
echo "===================================================================="
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"name": "multi-agent-mux",
|
||||
"description": "Multi-Agent Orchestration & Messaging Backplane on Tmux & MQTT.",
|
||||
"disabled": false
|
||||
}
|
||||
Reference in New Issue
Block a user