Add server-side safeguards so heavy web workflows cannot crash Apache: - Run-concurrency gate: whole run/series_run_candidate requests lease flock slots under TMPROOT/.musrflow-run-slots (MUSRFIT_MAX_RUNS=2 default, MUSRFIT_MAX_RUNS_PER_IP optional per-client pool); saturated servers answer 503 server-busy and leases are released when the CGI process exits. - Per-child resource wrapper: every external command runs with RLIMIT_AS (MUSRFIT_CHILD_MEM_KB, 16 GiB), optional RLIMIT_CPU, and exec nice (MUSRFIT_CHILD_NICE=10) so a runaway child cannot starve Apache workers. - Retune MUSRFIT_CMD_TIMEOUT default 400 -> 360 (deploy knob). - Size/job backstops: POST body cap before CGI->new (413), write MSR cap (413), and MUSRFIT_MAX_JOBS refusal of new job folders (never deletes). - Exclude the .musrflow-run-slots dir from prune_stale_jobs and job counting. - Document the new knobs in cgi/README.md and add CGI hardening tests.
muSRFlow
muSRFlow is a desktop and web workflow for creating, editing, fitting,
plotting, and inspecting musrfit MSR files. It wraps the musrfit,
musrview, msr2data, and dump_header command-line tools, and provides
interactive plotting of the fitted parameters across runs.
User Manual
The end-user manual is built with Sphinx from
docs/source (reStructuredText). The built HTML and PDF live under
docs/_build. Rebuild it with:
cd docs
make html # HTML in docs/_build/html
make latexpdf # PDF at docs/_build/latex/muSRFlow.pdf
Desktop Development
Install Node.js and npm, then run:
npm install
npm start
Dependencies only need to be installed once. Later sessions can be started with
npm start.
Desktop Packages
The desktop app is at version 1.0.0-rc.1 (release candidate). Linux RPM
and AppImage release packages can be produced with:
npm run dist:rpm
npm run dist:appimage
See docs/DESKTOP_DEPLOYMENT.md for build,
runtime, and release requirements.
The remaining work before 1.0 and the prioritized improvements are tracked in
TODO.md. Per-release notes are in
CHANGELOG.md.
Web Deployment
The browser application consists of index.html, quick-start.html, ZGUI.css,
muSRFitweb.js, muSRFitRoot.js, muSRFitParameterPlot.js, and muSRFitlib.js. The web plot window uses
JSROOT to draw the ROOT files produced by musrview --root. Its server-side
runner is documented in
cgi/README.md.
Install both the browser files and CGI endpoint. The script targets the default Apache paths and hands the files to the web server's owner:
sudo ./scripts/deploy-web.sh
The web-only owner (apache/www-data/httpd) is auto-detected when the
deployed tree is not already owned by the invoking user, so the script also
runs unprivileged against a developer-owned web tree (skip that case's sudo).
Override the targets and owner as needed with MUSRFLOW_WEB_TARGET,
MUSRFLOW_CGI_TARGET, MUSRFLOW_STARTUP_XML_TARGET, MUSRFLOW_WEB_OWNER, and
MUSRFLOW_WEB_GROUP.
The installed musrfit_startup.xml is rewritten when the machine's data tree
lives under a non-PSI root: set MUSRFLOW_DATA_ROOT (e.g. /mnt/fake) and the
<data_path> roots in the installed copy are rewritten to it so the portable
RUN-name resolver matches the local data layout. The repository source file is
never modified.
The server-side data root is configured separately: the CGI reads
MUSRFIT_DATA_ROOT (default /psi.ch/group/lmu/public/data) and reports it to
the browser through its health endpoint. When MUSRFLOW_DATA_ROOT is used,
set MUSRFIT_DATA_ROOT to the same value so the path the browser shows and the
security boundary agree with the rewritten startup-XML roots. See
cgi/README.md for the full list of CGI environment variables.
Code Organization
The project splits platform code from shared logic so that a change is made once instead of duplicated across the desktop and web runtimes:
muSRFitlib.js— shared, platform-agnostic logic (MSR generation/parsing, series-fit planning and merge, fit-statistic parsing, shared-configuration protocol, command/parameter formatting). This is the canonical home for any logic that both runtimes need.muSRFitelec.js— Electron-specific code (filesystem and IPC access, local process execution, local transaction adapter).muSRFitweb.js— web-specific code (CGI transport, browser clipboard, drag-and-drop windows).
As a rule, the adapters supply only platform-specific primitives (filesystem,
process, clipboard, HTTP) while muSRFitlib.js owns the logic. Pure
transformations such as displayCommand, seriesRunDirectiveIdentity, and
normalizeParameterDataHeaderLines live in muSRFitlib.js. The CGI endpoint
writes files and runs external executables on the server; generated artifacts
are served back over HTTP.
Contact
Zaher Salman zaher.salman@psi.ch
License
Copyright (C) 2026 Zaher Salman. muSRFlow is distributed under the
GNU General Public License, version 3 or later (GPL-3.0-or-later). See
LICENSE for the full license text.