How to install CASA on AWS
==========================

This guide explains how to install the monolithic CASA distribution locally for an individual user
on AWS, without requiring a system-wide installation.

Related
-------

- :doc:`How to start an interactive compute node on AWS <aws-interactive-compute-node>`
- `Accessing the clusters (Confluence)
  <https://confluence.skatelescope.org/display/SE/Accessing+the+clusters>`_
- `CASA Guides <https://casaguides.nrao.edu/index.php/Main_Page>`_

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

- An account on AWS and access to the head node.

Steps
-----

.. note::

    If you want CASA GUI support, ensure that you have enabled the ``-Y`` flag when connecting to
    the head node via ``ssh``.

1. Create and enter a directory where the CASA tar file will be downloaded and unpacked. In this
   example, we use ``$HOME/software/casa``:

       .. code-block:: bash

           mkdir -p "$HOME/software/casa"
           cd "$HOME/software/casa"

2. Navigate to the official `CASA download page <https://casa.nrao.edu/casa_obtaining.shtml>`_ and
   find the latest stable release for Linux. At the time of writing, the latest version is CASA
   6.7.3. So the command would be:

       .. code-block:: bash

           wget -c https://casa.nrao.edu/download/distro/casa/release/rhel/casa-6.7.3-21-py3.12.el9.tar.xz

3. Unpack the downloaded tar file:

       .. code-block:: bash

           tar -xvf casa-6.7.3-21-py3.12.el9.tar.xz

   This should create a directory called ``casa-6.7.3-21-py3.12.el9`` containing the CASA
   executables under ``bin``. The tarfile can be deleted after successful unpacking.

4. CASA ships with its own ``python`` and ``pip`` aliases that point to the ``casa`` executable. To
   avoid confusion, instead of adding ``casa-6.7.3-21-py3.12.el9/bin`` to your ``PATH``, we
   recommend creating symbolic links to specific executables in ``~/.local/bin``.

       .. code-block:: bash

           ln -s "$HOME/software/casa/casa-6.7.3-21-py3.12.el9/bin/casa" "$HOME/.local/bin/casa"
           ln -s "$HOME/software/casa/casa-6.7.3-21-py3.12.el9/bin/mpicasa" "$HOME/.local/bin/mpicasa"
           ln -s "$HOME/software/casa/casa-6.7.3-21-py3.12.el9/bin/casaviewer" "$HOME/.local/bin/casaviewer"

   Replace ``casa-6.7.3-21-py3.12.el9`` with the actual name of the unpacked CASA directory if the
   version is different.

5. Ensure that ``~/.local/bin`` is in your ``PATH``. You can check this by running:

       .. code-block:: bash

           echo $PATH

   If ``~/.local/bin`` is not in your ``PATH``, you can add it by adding the following line to your
   shell configuration file (e.g. ``~/.bashrc``):

       .. code-block:: bash

           export PATH="$HOME/.local/bin:$PATH"

   After adding this line, reload your shell configuration:

       .. code-block:: bash

           source ~/.bashrc

6. Before starting CASA for the first time, ensure that ``$HOME/.casa/data`` exists so that a
   minimal data repository can be downloaded by CASA to this standard location (if you prefer a
   different location, start ``casa`` without creating this directory and follow the instructions in
   the displayed error message):

       .. code-block:: bash

           mkdir -p "$HOME/.casa/data"

   CASA will download a minimal data repository to this location on the first run.

Verification
------------

Check that the ``casa`` command is available:

.. code-block:: bash

    which casa

This should print something like:

.. code-block:: text

    /home/<your-username>/.local/bin/casa

Start CASA:

.. code-block:: bash

    casa

CASA should start and drop you into the CASA command prompt.

.. note::

    CASA will attempt to open the GUI logger by default. If the ``-Y`` flag was not set when
    connecting to the head node via ``ssh``, CASA IPython interpreter will still work but GUI tools
    will not be available. Alternatively, you can start CASA with the following options to disable
    the GUI logger and log to the terminal instead:

        .. code-block:: bash

            casa --nologger --log2term

.. warning::

    We do not recommend running computation-intensive CASA tasks on the head node, including
    interactive tasks such as ``plotms``. Make sure you are on an interactive compute node before
    running CASA on any large data set.

FAQ
---

**Q: Why install CASA this way instead of using a system-wide module?**

A: This method is intended for occasional local use, testing, debugging, and interactive inspection
of data products. The monolithic CASA distribution is not always efficient for server use or large
data sets; tools such as ``plotms`` can be slow with large Measurement Sets, sometimes taking many
minutes to display data even locally, and may be unstable or crash unexpectedly. For routine data
processing or large-scale data analysis, use more targeted data processing tools and pipelines
available on AWS. For quick plotting of large data sets, use tools such as ``shadems`` available on
AWS.

**Q: Can I install multiple CASA versions?**

A: Yes. Keep each CASA version in its own directory under ``$HOME/software/casa`` and update the
symbolic link in ``~/.local/bin`` to point to the version you want to use.