Deploy Runbook

Two things live here: deploying the MuseHub server and publishing a new Muse CLI build.

0 — Build frontend assets (required before deploy)

The Docker image copies compiled assets directly from the working tree. app.css and app.js are in .museignore (not committed), so they must be built locally before running push.sh.

cd ~/ecosystem/musehub
npm run build        # compiles src/scss → app.css and src/ts → app.js

Or rebuild only what changed:

npm run build:css    # SCSS only  (src/scss/app.scss → musehub/templates/musehub/static/app.css)
npm run build:js     # TS only    (src/ts/app.ts → musehub/templates/musehub/static/app.js)

Source files to edit (never edit the compiled output directly):

During local development, use the watch commands to rebuild automatically on save:

npm run watch:css    # rebuilds app.css on every SCSS change
npm run watch:js     # rebuilds app.js on every TS change

1 — Deploy MuseHub (server)

bash deploy/push.sh staging          # build, push to ECR, blue-green deploy
bash deploy/push.sh prod             # same for prod
bash deploy/push.sh staging prod     # staging then prod in sequence
IMAGE_TAG=<prev-tag> bash deploy/push.sh staging   # rollback to a prior image

push.sh does a full blue-green deploy: builds a Docker image for linux/amd64, pushes it to ECR, starts the inactive slot, health-checks /healthz, switches nginx, and stops the old slot. The image tag is <short-commit-id>-<YYYYMMDDHHMMSS>.

For full infrastructure details (instance IDs, slot switching, SSM recovery) see infrastructure.md.

2 — Publish a new Muse CLI build

bash deploy/publish_muse_release.sh

Run from the musehub repo root. It reads the version from ~/ecosystem/muse/pyproject.toml automatically.

What it does:

1. Builds muse-<version>.tar.gz from ~/ecosystem/muse using python3 -m build
2. Uploads the tarball to s3://musehub-releases/
3. SSMs into staging and copies it to /data/releases/ on the instance volume
4. Prunes S3 and the instance to keep only the 3 most recent tarballs
5. Smoke-tests https://staging.musehub.ai/releases/muse-<version>.tar.gz — exits non-zero on failure

After a successful run, the new version is live and anyone running the installer gets it:

curl -fsSL https://staging.musehub.ai/install.sh | sh

Prerequisites

• Python 3.14 + build package: pip install build
• AWS CLI configured with credentials that can write to s3://musehub-releases and send SSM commands to i-07547cd20bee2dea5

Override version label

MUSE_VERSION=0.2.1 bash deploy/publish_muse_release.sh

Useful if you need to re-publish a tarball under a different version label without editing pyproject.toml.

Standard release flow

# 1. Bump version in both pyproject.toml files (muse + musehub), commit, merge to main, push
# 2. Deploy the new MuseHub server (so install.sh serves the right version string)
bash deploy/push.sh staging

# 3. Publish the Muse CLI tarball
bash deploy/publish_muse_release.sh

# 4. Verify
curl -fsSL https://staging.musehub.ai/install.sh | sh
muse --version

Steps 2 and 3 are independent but 2 should come first — install.sh is generated dynamically from MUSE_VERSION in musehub/protocol/version.py, so the server must be running the new version before the tarball is published.