Installing RAFT
===============

Overview
--------

Install RAFT before choosing where you want to run it. RAFT itself installs as
a Python package, but some execution modes also require external tools or cloud
credentials.

Local prerequisites
-------------------

For local and hybrid usage, install:

- Python 3.9+
- Git
- 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.

Installing Apptainer or Singularity
-----------------------------------

If your current conda-based Apptainer install is not working, prefer your
operating system package manager instead.

Use one of the following common approaches:

- Ubuntu or Debian:

  .. code-block:: console

    $ sudo apt update
    $ sudo apt install -y apptainer

- Fedora:

  .. code-block:: console

    $ sudo dnf install -y apptainer

- RHEL, Rocky, AlmaLinux, or CentOS:

  .. code-block:: console

    $ sudo yum install -y epel-release
    $ sudo yum install -y apptainer

- openSUSE:

  .. code-block:: console

    $ sudo zypper install apptainer

- Arch Linux:

  .. code-block:: console

    $ sudo pacman -S apptainer

If your distribution does not package ``apptainer`` directly, install
``singularity`` if that is the name provided by the distribution package
manager.

After installation, confirm that the runtime is visible on ``$PATH``:

.. code-block:: console

  $ apptainer --version

or:

.. code-block:: console

  $ singularity --version

Installing 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``.

Setting up RAFT
-----------

RAFT requires a directory consisting of various folders including: ``projects/``, ``references/``, and ``inputs/``. This directory will also contain the RAFT configuration file.

To set up RAFT, run:

.. code-block:: console

  $ raft setup

You will be prompted to provide paths for each required subdirectory, with
sensible defaults.

A default installation, in which all subdirectories are created in the current
working directory, can be created by running:

.. code-block:: console

  $ raft setup --default

Cloud prerequisites
-------------------

For the experimental GCP BYOC launcher, you typically need:

- a GCP project you control
- a GCS bucket you control
- a RAFT runner image accessible to Batch
- sufficient IAM permissions to upload objects and submit Batch jobs

.. note::

   Bucket names cannot contain underscores. Use hyphens instead.

For the advanced CLI ``--bucket gs://...`` path, RAFT also expects local
Google Application Default Credentials (ADC). A common setup is:

.. code-block:: console

  $ gcloud auth application-default login

RAFT does not create ADC credentials for you.