==============================
CMSW Installation Instructions
==============================

This document describes the installation workflow for the
Cabinet Management Software (CMSW). It covers installation for both:

- Subrack systems (ARMv7, online or offline)
- External development or staging machines

It includes the usage of the deployment script ``deploy.sh``.

Prerequisites
=============

System Requirements
-------------------

- ARMv7 Linux (for subracks)
- Python 3.11 will be installed and managed automatically via ``uv``
- ``bash`` shell
- Optional: Internet access (for automated updates and downloads)

Subrack Setup
=============

This is the initial deployment procedure for a **fresh subrack**.

The recommended way to execute the initial setup is:

.. code-block:: bash

    source deploy.sh --first-time-subrack

When this option is used, the deploy script performs the following steps:

1. Deactivates any currently active virtual environment.
2. Detects internet availability.
3. Optionally updates the repository from a specified git branch
   (only if ``--branch <name>`` is provided and internet is available).
4. Verifies whether ``uv`` is installed:

   - If found, it is used immediately.
   - If missing, the script checks for a local tarball in ``./tarball``.
   - If the tarball is missing but internet is available, the script downloads it.
   - If neither is possible, the script instructs the user to download the tarball externally and place it into ``./tarball``.

5. Extracts ``uv`` and installs it into ``$HOME/.local/bin``.
6. Creates a fresh virtual environment (only if online):

   - Removes any existing ``.venv``.
   - Runs ``uv lock`` and ``uv sync`` - this automatically downloads Python 3.11 and creates a venv if needed.
   - Activates the new environment.

7. If offline:

   - If ``.venv`` already exists, it is activated.
   - If ``.venv`` does not exist, the script aborts.

Examples
--------

**Initial setup using the default branch (no git update):**

.. code-block:: bash

    source deploy.sh --first-time-subrack

**Initial setup with git update to the latest ``main`` branch:**

.. code-block:: bash

    source deploy.sh --first-time-subrack --branch main

**Initial setup specifying a different branch:**

.. code-block:: bash

    source deploy.sh --first-time-subrack -b janus-365

Standard Deployment Workflow
============================

For deployments on a subrack where first-time setup had already been done, 
OR for deployment on a server (first-time or otherwise), run:

.. code-block:: bash

    source deploy.sh

This performs:

- Optional git update (if ``--branch`` is specified and internet is available)
- Optional ``uv`` tarball download (``--download-uv``)
- Check for ``uv`` (if not found, then raises error with installation instructions)
- Standard environment update (``uv lock`` + ``uv sync``)
- Activation of the environment

Git Update
----------

To update the repository from a specific branch:

.. code-block:: bash

    source deploy.sh --branch main

If no internet is available, the script skips git updates automatically.

Downloading the ``uv`` Tarball
-------------------------------

To explicitly download the correct ``uv`` ARMv7 tarball into ``./tarball``:

.. code-block:: bash

    source deploy.sh --download-uv

You may later transfer this tarball to an offline subrack by ``scp`` and then run on the subrack:

.. code-block:: bash

    source deploy.sh --first-time-subrack

Offline Subrack Behaviour
=========================

If a subrack does not have internet access:

- Git updates are skipped.
- ``uv`` installation works only if the tarball exists in ``./tarball``.
- The virtual environment is activated only if ``.venv`` already exists;
  otherwise, installation halts and the user is instructed to perform the
  setup on a machine with internet access.

Environment Activation Notes
============================

Because ``deploy.sh`` is designed to be *sourced*, not executed, use:

.. code-block:: bash

    source deploy.sh ...

not:

.. code-block:: bash

    ./deploy.sh

Sourcing ensures that the activated virtual environment remains active
after the script completes.

Troubleshooting
===============

``deactivate: command not found``
---------------------------------

This message appears if ``deactivate`` is called when no virtual
environment is active. The script checks this safely and ignores errors.

``ERROR: uv not installed, no local tarball, and no internet.``
----------------------------------------------------------------

This occurs during ``--first-time-subrack`` if:

- ``uv`` is not present
- No tarball is in ``./tarball``
- No internet is available

Solution:

Download the UV tarball externally:

.. code-block:: bash

    source deploy.sh --download-uv

Then copy the tarball to the subrack:

.. code-block:: bash

    scp uv-armv7-unknown-linux-gnueabihf.tar.gz <user>@<subrack_ip>:~/ska-low-sps-cabinet-cmsw/scripts/tarball/

Run the script again on the subrack:

.. code-block:: bash

    source deploy.sh --first-time-subrack