Metadata-Version: 2.4
Name: zmon
Version: 1.5.0
Summary: Monitoring for zCFD runs
Author-email: Zenotech <support@zenotech.com>
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi
Requires-Dist: uvicorn
Provides-Extra: test
Requires-Dist: httpx; extra == "test"

# zMon

zMon is a monitoring application featuring a React-based frontend (using Vite) and an Express backend, both running on [Bun](https://bun.sh).

## 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](https://bun.sh) 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](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:

```bash
./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:

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

The API is served under `/api/monitor`. When mounted in zui, the frontend reads
`window.ZMON_CONFIG = { baseUrl, token }`; standalone it needs no configuration.

## Development Instructions

From the root of the project, install dependencies once:

```bash
bun install
```

Then start both the frontend and backend dev servers together:

```bash
./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:

```bash
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:

```bash
./zmon-package
```
or
```bash
bun run package
```
or
```bash
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.
