diff --git a/README.md b/README.md index 1e21520..23ba6eb 100644 --- a/README.md +++ b/README.md @@ -52,14 +52,23 @@ Repository metadata is also provided in [CITATION.cff](CITATION.cff). ### Supported platforms ### -* [Linux] +* [Linux] (RPM, DEB, Flatpak packages; run from source) +* [Windows] (NSIS installer with bundled WSL2 engine runtime) * Online at: http://musruser.psi.ch/TRIMSP-NL/ * Source repository: https://gitea.psi.ch/LMU/TRIMSP ### Installation ### -Packages are not stored in this repository. You can either run the application -directly from source or build Linux packages locally as described below. +**Start with the guide for your platform.** Packaged desktop applications do +not require Node.js or npm. + +| Platform | Instructions | Engine | +| --- | --- | --- | +| **Windows** | **[Install on Windows](docs/install-windows.md)** | Bundled; runs inside a private WSL2 distribution (installed on first launch). | +| **Linux** | **[Install on Linux](docs/install-linux.md)** | Bundled static `trimspNL` in RPM/DEB/Flatpak packages. | +| **Web** | Open your site's TRIMSP-NL URL in a browser. | Runs on the server via the CGI runner. | + +For development and packaging from source, see below. ###### Fortran code compilation ###### @@ -233,13 +242,29 @@ which matches how the packaged app currently handles simulation input/output. ###### Deploying on a web server ###### -The repository includes the browser assets, CGI runner, and a deployment -script for an Apache-style server. With the default settings, run: +The repository includes the browser assets, CGI runner, and deployment scripts +for an Apache-style server. With the default settings, run: ```bash sudo ./scripts/deploy-web.sh ``` +To deploy to a remote server (e.g. musruser.psi.ch) from this machine, +`deploy-remote-web.sh` copies a tarball, extracts it on the remote host, and +runs `deploy-web.sh` via sudo (the remote user must have sudo rights): + +```bash +./scripts/deploy-remote-web.sh [path/to/TrimSP.tar.gz] +# or let it create a temporary archive from the current tree: +./scripts/deploy-remote-web.sh +``` + +Set `TRIMSP_REMOTE_HOST` / `TRIMSP_REMOTE_USER` / `TRIMSP_REMOTE_SSH` as +needed. `TRIMSP_WEB_TARGET`, `TRIMSP_CGI_TARGET`, `TRIMSP_BIN_PATH`, +`TRIMSP_PLOTLY_CDN`, `TRIMSP_WEB_OWNER`, and `TRIMSP_WEB_GROUP` are passed +through to the remote `deploy-web.sh`. `TRIMSP_BIN_PATH` must point to the +`trimspNL` engine **on the remote host**. + The script expects the TRIM.SP-NL engine to be installed already and installs: ```text @@ -315,3 +340,4 @@ Zaher Salman [Linux]: https://en.wikipedia.org/wiki/Linux [Monte Carlo]: https://en.wikipedia.org/wiki/Monte_Carlo_method [GUI]: https://en.wikipedia.org/wiki/Graphical_user_interface +[Windows]: https://en.wikipedia.org/wiki/Microsoft_Windows diff --git a/docs/install-linux.md b/docs/install-linux.md new file mode 100644 index 0000000..c06d67c --- /dev/null +++ b/docs/install-linux.md @@ -0,0 +1,73 @@ +# Install TRIMSP-NL Workbench on Linux + +TRIMSP-NL Workbench is available as RPM, DEB, and Flatpak packages built from +this source tree, or you can run it directly from source. The Linux desktop +application bundles the statically linked `trimspNL` Fortran engine; Node.js +and npm are not needed on the target PC. + +Replace `` below with the package version you obtained (current +development line: see `package.json`). + +## Install from a package + +### RPM (dnf/rpm-based distributions) + +```bash +sudo dnf install ./trimsp--1.x86_64.rpm +trimsp +``` + +On Mageia/openSUSE/Fedora use your distribution's package manager. The RPM +depends on GTK 3. + +### DEB (Debian/Ubuntu-based distributions) + +```bash +sudo apt install ./trimsp__amd64.deb +trimsp +``` + +### Flatpak + +```bash +flatpak install --user ./ch.psi.lem.TrimSP_stable_x86_64.flatpak +flatpak run ch.psi.lem.TrimSP +``` + +Flatpak builds are produced with `npm run make:flatpak` (requires +electron-forge flatpak tooling). + +## Running from source (development) + +Install Node.js/npm and the Fortran toolchain (`gfortran`, `make`): + +```bash +cd trimsp +npm install +npm start +``` + +Build the static engine (bundled in packages) or the dynamic one: + +```bash +npm run build:fortran # static -> resources/bin/trimspNL +npm run build:fortran:dynamic # dynamic -> resources/bin/trimspNL +``` + +## First run + +1. Launch TRIMSP-NL Workbench. +2. Set a writable **Work Folder** (outside the application installation directory). +3. Configure your target/scan and click **Run**. Results (`*_E*.rge`, + `_Seq_Results.dat`, etc.) are written to the work folder. + +## Building packages locally + +```bash +npm ci +npm run make # deb + rpm (forge, static engine) +npm run make:flatpak # flatpak +npm run checksums # md5 + sha256 sidecars +``` + +Artifacts are written under `out/make/deb/x64/` and `out/make/rpm/x64/`. diff --git a/docs/install-windows.md b/docs/install-windows.md new file mode 100644 index 0000000..d6b2e26 --- /dev/null +++ b/docs/install-windows.md @@ -0,0 +1,78 @@ +# Install TRIMSP-NL Workbench on Windows + +The Windows installer (`TRIMSP-NL-Workbench-Setup.exe`) includes the application +and the `trimspNL` engine. Windows cannot run the Linux engine natively, so the +engine runs inside a bundled **WSL2** distribution that the app prepares on +first launch. You do not need Node.js, npm, or a separate engine installation. + +## Before you start + +- **64-bit Intel/AMD PC** (x64). +- **WSL2** must be installed and updated. Windows 11 is recommended. +- Administrator access is needed once to enable WSL/virtualization features. +- Obtain `TRIMSP-NL-Workbench-Setup.exe` from the project release (see + [README](../README.md)). The installer is unsigned, so Windows may show + its normal unsigned-publisher warnings. + +## Install step by step + +1. **Install WSL.** Open **PowerShell as Administrator** and run: + + ```powershell + wsl --install --no-distribution + ``` + + **Restart Windows.** Skip if WSL is already installed. TRIMSP supplies its own + distribution, so Ubuntu is not required. + +2. **Update and check WSL.** + + ```powershell + wsl --update + wsl --version + ``` + + The output should include WSL and a recent kernel. See + [Microsoft's WSL documentation](https://learn.microsoft.com/en-us/windows/wsl/install). + +3. **Install TRIMSP-NL Workbench.** Run `TRIMSP-NL-Workbench-Setup.exe`. The + WSL2 runtime archive is bundled inside the installer — do not extract or + import it manually. + +4. **Launch the app** from the Start menu as your normal Windows user. On first + launch the app imports the bundled runtime as the `trimspNL-runtime` WSL2 + distribution into `%LOCALAPPDATA%\TrimSP\trimspNL-runtime` (first run can + take a minute). Progress is shown in the status bar; the first simulation + waits for the import to finish. Verify afterwards: + + ```powershell + wsl --list --verbose + ``` + + `trimspNL-runtime` should appear with **VERSION 2**. + +5. **Choose a work folder and run.** Set a writable **Work Folder** on a Windows + drive (e.g. `C:\Users\\TrimSP\work`). Enter normal Windows paths — the + app translates them for the engine running in WSL. Click **Run** and confirm + `_E*.rge` and `_Seq_Results.dat` appear in the work folder. + +## Updating + +Install the new application over the previous one. Reinstalling the app +preserves an already-imported `trimspNL-runtime` distribution; a new runtime +image is only imported when needed. Keep your work folders outside the +application install directory. + +## Troubleshooting + +- **Import/preparation fails:** ensure WSL2 is installed and updated + (`wsl --status`, `wsl --version`) and that virtualization is enabled in + BIOS/UEFI. See + [WSL troubleshooting](https://learn.microsoft.com/en-us/windows/wsl/troubleshooting). +- **Engine/run issues:** check the run log in the app. You can confirm the + engine inside the distro with + `wsl -d trimspNL-runtime -- /opt/trimsp-runtime/bin/trimspNL`. +- **Remote sessions (RDP/SSH):** the engine is console-only and does not use the + display; file dialogs and windows follow Electron's normal behavior on Windows. + +Include the app version and run log when reporting a problem. diff --git a/scripts/deploy-remote-web.sh b/scripts/deploy-remote-web.sh new file mode 100755 index 0000000..1b12e59 --- /dev/null +++ b/scripts/deploy-remote-web.sh @@ -0,0 +1,106 @@ +#!/usr/bin/env bash +# Copyright (C) 2026 Zaher Salman +# SPDX-License-Identifier: GPL-3.0-or-later +# +# Deploy TRIMSP-NL Workbench web assets to a remote host (e.g. musruser.psi.ch). +# Copies the required files to a temporary directory on the remote host, +# then runs deploy-web.sh there with sudo so the web server can read/execute them. +# +# Usage: +# ./scripts/deploy-remote-web.sh [path/to/TrimSP.tar.gz] +# +# If no tarball is given, a temporary tar.gz is created from the current +# working tree. Run "npm install" first so the Plotly bundle is available +# locally (otherwise deploy-web.sh will fetch it from CDN on the target). +# +# Environment: +# TRIMSP_REMOTE_HOST Remote host (default: musruser.psi.ch) +# TRIMSP_REMOTE_USER SSH user (default: current user) +# TRIMSP_REMOTE_SSH Extra ssh/scp options (e.g. "-J jumphost") +# TRIMSP_REMOTE_TMP Remote temp base dir (default: /tmp) +# TRIMSP_WEB_TARGET Passed through to deploy-web.sh +# TRIMSP_CGI_TARGET Passed through to deploy-web.sh +# TRIMSP_BIN_PATH Passed through to deploy-web.sh (engine on remote host) +# TRIMSP_PLOTLY_CDN Passed through to deploy-web.sh +# TRIMSP_WEB_OWNER Passed through to deploy-web.sh +# TRIMSP_WEB_GROUP Passed through to deploy-web.sh +# +# The remote user must be able to run: sudo ./scripts/deploy-web.sh +# (passwordless sudo for that command, or you will be prompted if TTY allows). + +set -euo pipefail + +project_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +remote_host="${TRIMSP_REMOTE_HOST:-musruser.psi.ch}" +remote_user="${TRIMSP_REMOTE_USER:-}" +remote_ssh_opts=(${TRIMSP_REMOTE_SSH:-}) +remote_tmp_base="${TRIMSP_REMOTE_TMP:-/tmp}" + +if [ -n "$remote_user" ]; then + remote="${remote_user}@${remote_host}" +else + remote="${remote_host}" +fi + +tarball="${1:-}" +cleanup_tarball="" +if [ -z "$tarball" ]; then + tarball="$(mktemp "${TMPDIR:-/tmp}/trimsp-deploy.XXXXXX.tar.gz")" + cleanup_tarball="$tarball" + printf 'Creating temporary deployment archive: %s\n' "$tarball" + # Include only what deploy-web.sh needs. + tar -C "$project_root" -czf "$tarball" \ + TrimSP.html quick-start.html TrimSPlib.js TrimSPweb.js myplots.js \ + ZGUI.css plotly.css icon.png package.json \ + singleTrimSP.cgi scripts/deploy-web.sh \ + node_modules/plotly.js-dist/plotly.js +fi + +if [ ! -f "$tarball" ]; then + printf 'Tarball not found: %s\n' "$tarball" >&2 + exit 1 +fi + +remote_dir="${remote_tmp_base}/trimsp-deploy.$$.$(date +%s)" +remote_tar="${remote_dir}/$(basename "$tarball")" + +printf 'Copying %s to %s:%s\n' "$tarball" "$remote" "$remote_dir" +ssh "${remote_ssh_opts[@]}" "$remote" "mkdir -p '$remote_dir'" +scp "${remote_ssh_opts[@]}" "$tarball" "$remote:$remote_tar" + +# Build env assignments for remote deploy-web.sh +env_args=() +for var in TRIMSP_WEB_TARGET TRIMSP_CGI_TARGET TRIMSP_BIN_PATH \ + TRIMSP_PLOTLY_CDN TRIMSP_WEB_OWNER TRIMSP_WEB_GROUP; do + val="${!var-}" + if [ -n "$val" ]; then + esc="${val//\'/\'\\\'\'}" + env_args+=("$var='$esc'") + fi +done + +printf 'Extracting and deploying on %s (sudo)...\n' "$remote" +ssh "${remote_ssh_opts[@]}" -t "$remote" bash -s -- "$remote_dir" "$remote_tar" "${env_args[*]-}" <<'REMOTE' +set -euo pipefail +remote_dir="$1"; remote_tar="$2"; env_assign="${3-}" +cd "$remote_dir" +tar -xzf "$remote_tar" +if [ -f scripts/deploy-web.sh ]; then + root=. +elif [ -f */scripts/deploy-web.sh ]; then + root="$(dirname "$(echo */scripts/deploy-web.sh | awk '{print $1}')")" +else + echo "deploy-web.sh not found after extraction" >&2; exit 1 +fi +cd "$root" +# shellcheck disable=SC2086 +sudo env $env_assign ./scripts/deploy-web.sh +cd / +rm -rf "$remote_dir" +REMOTE + +if [ -n "$cleanup_tarball" ]; then + rm -f "$cleanup_tarball" +fi + +printf 'Remote deployment to %s complete.\n' "$remote"