Running RAFT locally
====================

Prerequisites
-------------

RAFT installs as a Python package, but running workflows locally also requires
several external tools:

- Python 3.9+
- Nextflow
- Singularity or Apptainer

.. note::

   RAFT provides a ``--bypass-dependencies`` flag for advanced cases, but the
   recommended setup is to install the required system dependencies normally.

Install RAFT
------------

Install RAFT with pip:

.. code-block:: console

  $ pip install --user reproducible-analyses-framework-and-tools

Depending on your environment, you may need to add ``~/.local/bin`` to your
``$PATH``.

Set up a workspace
------------------

Initialize the standard RAFT workspace in your current directory:

.. code-block:: console

  $ raft setup --default

This creates ``.raft.cfg`` and the standard directories such as:

  - ``projects/``
  - ``references/``
  - ``imgs/``
  - ``shared/``
  - ``inputs/``

If you want to place those directories in custom locations, run:

.. code-block:: console

  $ raft setup

Try the demo
------------

Run a demo project:

.. code-block:: console

  $ raft run-demo --workflow lens --version v1.9-dev

Run your own project
--------------------

Create and run a project:

.. code-block:: console

  $ raft run \
      --project-id my-project \
      --workflow lens \
      --version v1.9-dev \
      --manifest my_manifest.tsv

.. note::
   if ``--manifest`` is omitted, RAFT will launch the web-based manifest generator.

.. note::
   if ``--workflow-profile`` is omitted, RAFT will launch the web-based workflow configuration tool.

If a project already exists, run it again with:

.. code-block:: console

  $ raft run --project-id my-project

Do not repeat setup-only flags such as ``--workflow``, ``--version``,
``--manifest``, or ``--setup-only`` when running an existing project. RAFT
treats those as project-creation options and will refuse to mix them with an
existing project run.

If you want workflow-specific recommended profiles in the documentation, those
should be listed on the workflow inventory page and passed via
``--workflow-profile``.

For additional setup and execution flags, see :doc:`helpful-raft-options`.
For common errors and next-step commands, see :doc:`troubleshooting`.

Manage existing projects
------------------------

After you have run one or more projects, use ``raft generate-reports`` to
review outputs and the project packaging/loading commands to transfer or archive
projects.