Skip to content

release.md

Latest commit

 

History

History
171 lines (114 loc) · 5.65 KB

release.md

File metadata and controls

171 lines (114 loc) · 5.65 KB
Raw

Alpha Release Guide

This guide describes the current alpha release path for DevMesh. It covers the Hub Server, Web Admin, Website, PostgreSQL runtime used by the Docker Compose stack, and the public devmesh CLI npm package.

Release Scope

The alpha release publishes deployable application artifacts and the public devmesh CLI package. Internal workspace packages remain private; the CLI bundles them into dist/index.js, while Docker images build them from source.

Included artifacts:

  • apps/mesh-server: Hub Server container.
  • apps/web-admin: static Web Admin container with /api proxied to the Hub Server.
  • apps/website: static documentation website container.
  • postgres: PostgreSQL service for durable knowledge and Hub state storage.
  • apps/dmx: public devmesh npm package that installs the dmx CLI.

Preflight

Run the full verification suite before creating a tag or building images. The release check synchronizes the publishable CLI package version from the workspace root, validates the git tag, and smoke-tests the packed npm CLI in a temporary install prefix:

pnpm install
pnpm release:check

To run only the packaged CLI install smoke locally:

pnpm npm:smoke

Known build warnings:

  • The Web Admin Vite build may report existing chunk-size and pure annotation warnings.

Local Docker Compose

Build and start the alpha stack:

pnpm docker:up

For background startup followed by a smoke check:

pnpm docker:up:detached
pnpm docker:smoke

Default URLs:

Hub Server: http://127.0.0.1:8721
MCP endpoint: http://127.0.0.1:8721/mcp
Web Admin: http://127.0.0.1:5173
Website: http://127.0.0.1:3000

Stop the stack:

pnpm docker:down

Remove local volumes when you intentionally want to reset PostgreSQL and server data:

pnpm docker:down:volumes

The same commands are summarized in ../deploy/README.md.

pnpm docker:smoke waits for the stack and checks:

  • Hub Server /healthz.
  • Hub Server /.well-known/devmesh.
  • Web Admin static shell.
  • Web Admin /healthz proxy.
  • Website home page.

Mesh Server Environment

Use deploy/mesh-server.env.example as the template for non-compose deployments:

cp deploy/mesh-server.env.example mesh-server.env

The server config precedence is:

CLI args > process env > env file

Run the built server directly:

pnpm build
node apps/mesh-server/dist/index.js --env-file ./mesh-server.env

Docker Images

Build individual images from the repository root:

docker build -f apps/mesh-server/Dockerfile -t devmesh-server:alpha .
docker build -f apps/web-admin/Dockerfile -t devmesh-web-admin:alpha .
docker build -f apps/website/Dockerfile -t devmesh-website:alpha .

The Docker Images GitHub workflow is manual-only for now, so v* tags can publish npm and GitHub Release artifacts without automatically publishing containers. When run manually, it publishes the three application images to GitHub Container Registry:

ghcr.io/<owner>/devmesh-server:<tag>
ghcr.io/<owner>/devmesh-web-admin:<tag>
ghcr.io/<owner>/devmesh-website:<tag>

Tag rules for manual runs:

  • Manual dispatch on a branch publishes manual-<run-number> and sha-<short-sha>.
  • Manual dispatch on a tag publishes <git-tag>, alpha, and sha-<short-sha>.

The workflow uses the repository GITHUB_TOKEN with packages: write; no registry password needs to be committed. The target registry can be switched to Docker Hub later without changing the npm or GitHub Release workflows.

Website Deployment

The Website Pages GitHub workflow builds the VitePress site and uploads apps/website/docs/.vitepress/dist to GitHub Pages. Enable Pages in repository settings before relying on the workflow.

GitHub Release Artifacts

The Release Artifacts GitHub workflow runs pnpm release:check, packages non-Docker artifacts, and uploads them as workflow artifacts. On v* tags, it also creates a GitHub Release with generated notes.

Release assets:

devmesh-web-admin-<tag>.tar.gz
devmesh-website-<tag>.tar.gz
devmesh-deploy-<tag>.tar.gz

The Web Admin and Website archives contain static files ready for any static host. The deploy archive contains README.md, deploy/, and this release guide.

NPM CLI Publishing

The NPM Publish GitHub workflow publishes the devmesh CLI package on v* tags. Manual dispatch builds and uploads the npm tarball as a workflow artifact without publishing.

Required repository secret:

NPM_TOKEN

The workflow publishes with provenance, public package access, and the alpha dist-tag:

npm install -g devmesh@alpha

The CLI package bundles internal workspace code into dist/index.js; runtime npm dependencies are limited to external packages used by the bundled CLI. The CLI package repository.url must match the GitHub repository used by Actions provenance.

Current Release Boundaries

  • Public npm publishing is enabled for the devmesh CLI only. Internal workspace libraries remain private and are bundled into the CLI.
  • Container image publishing is manual-only and currently targets GHCR; Docker Hub publishing can be wired in later without affecting npm releases.
  • GitHub Release artifacts currently cover static frontends and deployment docs; the Node server is released through source checkout or container images, not as a standalone npm package.
  • Web Admin is intended to be served behind the included Nginx proxy or another reverse proxy that forwards /api and /healthz to the Hub Server.
  • Production secrets and external PostgreSQL credentials should be provided through the deployment platform, not committed to the repository.