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:

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):

source deploy.sh --first-time-subrack

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

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

Initial setup specifying a different branch:

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:

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:

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:

source deploy.sh --download-uv

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

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:

source deploy.sh ...

not:

./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:

source deploy.sh --download-uv

Then copy the tarball to the subrack:

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:

source deploy.sh --first-time-subrack