GodopuandClaude Opus 5.5
47fe24e07c
The update is a skill (decision 4); deploy/update.sh and the installed .mam_deploy/update.sh are gone. - Phase 1 (installed code, update.sh): publish the update marker under the exclusive admission lock; refuse before any change while a running row, a live herdr agent in the workspace on any running server, an open job (unreadable JSON included, dry_run not), a live loop marker or a monitor.lock held by a monitor the skills did not start (U3) is there - the calling agent (server + pane, its row and one running job) excepted (lib_py/update.py precheck, decisions 1 and 7). Stop the monitor (TERM, then KILL and restart it if it does not end; decision 2), handle a leftover backup by its state (U4), back up .agents, .mam_deploy, root files, .venv, the installer's .mam files and the registry (SQLite backup API under the registry lock) into .mam/update-backup/, then exec a copy of install_phase.sh outside the tree (decision 5). - The copy (no lib.sh/lib_py, bash 3.2) runs the installer in place; on failure it restores the backup and restarts the monitor from the restored tree; on success it runs phase 2, post_update.sh of the new tree, which converts the registry with lib_py.registry_format and restarts the monitor if it ran. The backup and the marker are removed at the end. - install.sh updates in place (decisions 3, 4, 9): install_state keys are set, one line each; no updater is installed and an old one (.mam_deploy/update.sh, or a root update.sh the manifest lists) is removed; framework files the new version no longer ships are deleted when unmodified, kept and listed when modified, and dropped from base/, the manifest and asset_hashes.txt; a local source's .mam is not staged. remove.sh knows the new skill; CI shellchecks its scripts; docs point at the skill. - test_issue8_update_state and test_deploy_layout td6/td27 run the skill. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
99 lines
4.8 KiB
Markdown
99 lines
4.8 KiB
Markdown
# 🚀 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 remote shell installer (via curl) that checks system requirements (`herdr`, `python3`), sets up a local python virtual environment (`.venv`), and performs 3-way refresh with key-level registry merge (Rev.2).
|
|
* **`install_mam.sh`**: A local-clone installer that copies rules/skills (`.agents/`), `AGENTS.md`, manifests, and asset hashes into target projects.
|
|
* **`lib_ownership.sh`**: Single source of truth for framework-owned files and key-level registry files.
|
|
* **Updates**: installed workspaces update with the `multi-agent-mux-update` skill (`bash .agents/skills/multi-agent-mux-update/scripts/update.sh`).
|
|
* **`remove.sh`**: Clean uninstaller script installed into target `.mam_deploy/remove.sh`.
|
|
* **`generate-env.sh`**: Environment configuration bootstrap helper.
|
|
* **`INSTALL.md`**: Detailed installation and quick-start user manual.
|
|
* **`plugin.json`**: Metadata declaration file to register MAM as an installable plugin for AI Agent coding platforms.
|
|
* **`gitea-ci.yml`**: CI/CD pipeline definition template for Gitea Actions (running ShellCheck linting, Python syntax checks, and pytest suite).
|
|
|
|
---
|
|
|
|
## 📦 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://git.godopu.com/tmpl/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. Local-Clone Installation
|
|
If you already have cloned this repository locally, you can port MAM to other local target projects:
|
|
```bash
|
|
bash deploy/install_mam.sh --target /path/to/your/project
|
|
```
|
|
Refer to **`INSTALL.md`** inside this directory for the full instructions and workflows.
|
|
|
|
> [!NOTE]
|
|
> `install_mam.sh` automatically deploys `.mam_deploy/remove.sh` into target workspaces, recording install manifests and asset hashes to enable clean updates and uninstalls.
|
|
|
|
### 3. Custom Fork / Private Mirror Installations
|
|
If you run a private mirror or fork, you can override the source URLs during installation using environment variables:
|
|
|
|
```bash
|
|
# Installing from a custom mirror (pipe prepends must be applied to the bash command)
|
|
curl -fsSL https://my-mirror.example.com/.../install.sh \
|
|
| MAM_REPO_URL=https://my-mirror.example.com/me/multi-agent-mux.git \
|
|
MAM_ARCHIVE_URL=https://my-mirror.example.com/me/multi-agent-mux/archive/main.tar.gz \
|
|
bash
|
|
|
|
# Updating an existing workspace against a mirror
|
|
MAM_INSTALLER_URL=https://my-mirror.example.com/.../install.sh bash .agents/skills/multi-agent-mux-update/scripts/update.sh
|
|
```
|
|
|
|
### 4. 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" }
|
|
]
|
|
}
|
|
```
|
|
|
|
### 5. Private NATS Broker & Submodule Integration (`nats-docker`)
|
|
For production deployments and private networks, MAM utilizes a dedicated NATS broker (`nats:2.12-alpine` with MQTT 3.1.1 and JetStream enabled). The container assets and deployment guides are managed in the `nats-docker` submodule:
|
|
|
|
```bash
|
|
# When cloning the repository with internal credentials:
|
|
git clone --recurse-submodules https://git.godopu.com/tmpl/multi-agent-mux.git
|
|
|
|
# Or initialize submodules in an existing clone:
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
> [!NOTE]
|
|
> `nats-docker` is an optional submodule hosted in the private repository `laa/nats-docker`. If cloning without internal credentials, omit `--recurse-submodules`. The MAM framework functions out-of-the-box using standard MQTT brokers configured in `.mam.env`.
|
|
|
|
Refer to [`nats-docker/PRIVATE_SERVER.md`](../nats-docker/PRIVATE_SERVER.md) and [`MESSAGING.md`](../MESSAGING.md) for detailed configuration, `.mam.env` generation, and security guidelines.
|
|
|
|
---
|
|
|
|
## 🤖 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.
|