Add platform install docs and remote web deployment

- Add docs/install-windows.md and docs/install-linux.md (similar to
  muSRFlow's platform guides) covering the NSIS/WSL2 Windows installer and
  RPM/DEB/Flatpak Linux packages.
- README: link the platform guides and document Windows support; expand the web
  deployment section with deploy-remote-web.sh usage and the TRIMSP_REMOTE_*
  variables passed through to the remote host.
- scripts/deploy-remote-web.sh: new helper that tars the browser/CGI assets,
  copies them to a remote host, and runs deploy-web.sh via sudo, mirroring
  muSRFlow's remote deployment flow.
This commit is contained in:
salman committed 2026-11-16 10:24:59 +01:00
1 parent ad46a2ae11
commit cf4eeaf06c
4 files changed
+288 -5

No files matched your search

+31 -5
View File
@@ -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 <zaher.salman@psi.ch>
[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
+73
View File
@@ -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 `<version>` 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-<version>-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_<version>_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/`.
+78
View File
@@ -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\<you>\TrimSP\work`). Enter normal Windows paths — the
app translates them for the engine running in WSL. Click **Run** and confirm
`<prefix>_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.
+106
View File
@@ -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"