.. _linux-installation:

Linux installation
==================

Install the muSRFlow application, then select a working ROOT + musrfit
installation. **The Linux application package does not include the scientific
runtime.** You can use an existing installation or install the separate
runtime through Preferences. Node.js and npm are not needed on the target PC.

The current application packages are for x86_64 Linux. Examples below use
``1.0.0-rc.6``; substitute the version of the package you obtained. Run the
commands from the folder containing the downloaded files.

Install the application
-----------------------

Choose one application format.

RPM
~~~

On an RPM-based distribution with dnf:

.. code-block:: bash

   sudo dnf install ./musrflow-1.0.0-rc.6-x86_64.rpm
   musrflow

On other RPM systems, use the distribution's package manager. The application
RPM filename starts with lowercase ``musrflow``.

AppImage
~~~~~~~~

.. code-block:: bash

   chmod +x muSRFlow-1.0.0-rc.6-x86_64.AppImage
   ./muSRFlow-1.0.0-rc.6-x86_64.AppImage

The application AppImage filename starts with ``muSRFlow``. It requires a
compatible Linux desktop and AppImage/FUSE support. If it cannot start,
check the terminal output or use the RPM on a supported RPM distribution.

Set up ROOT and musrfit
-----------------------

Use an existing installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Open **File / Preferences**. Leave **musrfit binaries** on automatic detection
for a standard installation, or choose the directory containing ``musrfit``,
``musrview``, ``msr2data``, ``musrt0``, and ``dump_header``. Save your settings,
then use **Check tools** to verify the saved selection.

Install the separate runtime from a local bundle
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Obtain the runtime bundle for your architecture. Keep
   ``runtime-download.json`` and its matching ``musrflow-runtime-*.tar.gz``
   archive in the same folder. You do not need to unpack it.
2. Open **File / Preferences / Install runtime...** and select
   ``runtime-download.json``.
3. Review the versions and destination, then select **Install and use**.
   muSRFlow validates the archive, installs it in your personal application
   data directory, and selects its tools.
4. Use **Check tools** to confirm the selected runtime starts.

This installation does not require administrator access. Runtime downloads
are not automatic: obtain the bundle separately before opening the installer.
A compatible Linux system and desktop/display services are still required.

Alternative: system runtime RPM
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   sudo dnf install ./musrflow-runtime-1.0.0-rc.6-x86_64.rpm

This installs the runtime into ``/opt/musrflow/runtime``, which muSRFlow
recognizes automatically when no explicit tool directory takes precedence.

Alternative: runtime AppImage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For a user-writable runtime location:

.. code-block:: bash

   chmod +x musrflow-runtime-1.0.0-rc.6-x86_64.AppImage
   ./musrflow-runtime-1.0.0-rc.6-x86_64.AppImage --install "$HOME/.local/share/musrflow/runtime"

Launch the application with the installed runtime selected:

.. code-block:: bash

   MUSRFLOW_RUNTIME_ROOT="$HOME/.local/share/musrflow/runtime" musrflow

For the application AppImage, replace ``musrflow`` in that command with its
path. Leave **musrfit binaries** on automatic detection so the selected
runtime is used. Without a custom destination, the runtime AppImage installs
to ``/opt/musrflow/runtime`` and needs permission to write there. Its filename
is lowercase ``musrflow-runtime``, unlike the application AppImage.

Choose folders and test
-----------------------

1. In **File / Preferences**, choose a writable **Work directory** outside
   the application installation folder, for example ``~/muSRFlow/work``.
   Use **Browse...** to select it.
2. Set **Data directory** to the root of your instrument data tree, or to a
   writable folder such as ``~/muSRFlow/data`` for downloaded runs.
3. Leave **musrfit startup XML** on automatic detection unless you have a
   specific installation configuration, then save.
4. Select a known instrument, year, and run. Click **Plot**, then **Fit**.
   Confirm the spectrum opens, fitted parameters update, and output files
   appear in your work directory. Missing runs can be downloaded from
   ``musruser.psi.ch`` after confirmation when the server is reachable.

Updating and troubleshooting
----------------------------

* Upgrade the application RPM with your package manager, or replace the
  application AppImage. The separate runtime is not updated by an app upgrade.
* Preserve work files outside the application/runtime installation directories.
* For missing tools or shared libraries, run **Check tools** and inspect the
  reported executable paths. A configured binaries directory overrides
  automatic detection; clear an obsolete selection or choose the correct one.
* If fitting works but no spectrum window opens, inspect the run log and
  confirm your desktop session can display native musrview windows.
* If data are missing, check the instrument, year, run number, and data root.
  Downloaded files use the selected writable data root or the personal
  fallback folder reported in Preferences.

Include the application version and run log when reporting a problem.
