zMon

zMon is a monitoring application featuring a React-based frontend (using Vite) and an Express backend, both running on Bun.

Project Structure

• frontend/ - React frontend application (Vite + TypeScript)
• backend/ - Express backend server
• launcher/ - zmon / zmon.bat dispatcher script templates, copied into every release by zmon-package
• zmon/ - Python package replacing the Express backend (see below)
• zmon-setup - Prepares and runs the Python backend
• zmon-dev - Runs both servers for local development
• zmon-package - Builds and packages the application for distribution (see below)

Requires Bun to be installed for development and packaging. End users running a packaged release do not need Bun or Node installed — see below.

Python backend (in progress, branch python-wheel)

The Express/Bun backend is being replaced by a pip-installable Python package so zMon can ship inside zCFD, mount into zui's zCFD Dashboard tab, and be installed standalone to monitor jobs on a remote cluster. See docs/packaging-plan.md for the design and what remains.

One command does everything — create the virtualenv, install the package, build the frontend, and launch:

./zmon-setup data/override.py

It works from any directory (/path/to/zMon/zmon-setup mycase.py is fine, and relative case paths resolve against wherever you ran it), and re-running is instant because each step is skipped when it's already done. --setup-only prepares everything without launching.

Bun is not needed to run zMon, and zmon-setup will build the frontend with the existing frontend/node_modules if bun isn't installed. Bun is still the frontend build tool when it is available.

Launching serves the API and the built SPA on an unused port chosen by the OS and opens a browser. Add --no-browser to just print the URL. Useful flags:

• --port N — pin the port (for an SSH tunnel). Also ZMON_PORT.
• --host — defaults to 127.0.0.1; anything else exposes the file browser to other users on the machine.
• --exit-when-idle — shut down when no browser is connected (the old Bun behaviour). Off by default: it is unsafe behind an SSH tunnel.

Run the tests with:

./.venv/bin/python -m unittest discover -s tests

The API is served under /api/monitor. A host app embeds zMon with zmon.main.mount(app), which adds the API and the SPA at /monitor/; the page then takes #token=…, ?file=… and ?theme=… from its URL. zui's Monitor tab works this way — see "zui integration" in docs/packaging-plan.md for the contract.

Development Instructions

From the root of the project, install dependencies once:

bun install

Then start both the frontend and backend dev servers together:

./zmon-dev

This runs the backend directly with bun backend/server.js and the Vite dev server via bun run --filter frontend dev. The frontend is accessible at the URL Vite prints (usually http://localhost:5173) and communicates with the backend on its own port.

To run either side individually:

bun backend/server.js          # backend only
bun run --filter frontend dev  # frontend only

Build and Packaging Instructions

From the root directory of the project, run:

./zmon-package

or

bun run package

or

bun run build

This command will:

1. Install dependencies and build the frontend application.
2. Create a temporary release directory structure.
3. Compile the backend into a standalone Bun executable for every supported platform/architecture (bun build --compile, one binary per target), embedding all backend dependencies — no node_modules, no Bun or Node install required to run any of them.
4. Package everything into seven tarballs in the root directory:
   • zmon-<version>.tgz — a universal package containing every platform's binary (under bin/) plus zmon / zmon.bat launcher scripts that detect the local OS/architecture and dispatch to the right one. One download works everywhere.
   • zmon-<version>-<platform>.tgz — six single-architecture packages (linux-x64, linux-arm64, darwin-x64, darwin-arm64, windows-x64, windows-arm64), each containing just that platform's binary (named zmon / zmon.exe, no dispatcher needed) plus the frontend assets. Use these on a download page that lets users pick their platform directly, for a much smaller download than the universal package.
5. Clean up the temporary release directory.

Extracting the universal tarball produces:

zmon-<version>/
  zmon           - launcher for Linux/macOS: detects OS + architecture and execs the matching binary
  zmon.bat       - launcher for Windows: detects architecture and execs the matching binary
  bin/           - one compiled executable per target
  public/        - built frontend static assets

Extracting a single-architecture tarball produces just the binary and assets directly:

zmon-<version>-linux-x64/
  zmon           - (or zmon.exe on Windows packages)
  public/

Either way, end users just run ./zmon <file> (macOS/Linux) or zmon.bat <file> / zmon.exe <file> (Windows) — no runtime installation step.

Note: the backend no longer shells out to tail/grep (they don't exist on Windows) — the /api/log and /api/cycle-times endpoints stream and filter log files in pure JS instead (bounded memory regardless of log file size), so behavior is identical across all platforms.

Releasing to PyPI

• Stable release: run the Release App workflow from main. It bumps the version, tags vX.Y.Z, and dispatches Publish to PyPI against that tag.
• Feature trial: run the Trial Release workflow with your feature branch selected. It tags the branch head as the next alpha (e.g. v1.6.0a1, derived from the latest stable tag) and publishes it as a PyPI pre-release. Testers install it with pip install zmon==1.6.0a1 (or pip install --pre zmon); plain pip install zmon still gets the latest stable release.
• Re-publishing a tag by hand: gh workflow run pypi.yml --ref vX.Y.Z — the ref must be the tag, not a branch.