carta-controller 5.0.0-beta.1 → 5.0.0-beta.1c

package/config/example_config.json

@@ -4,7 +4,7 @@
         "pam": {
             "publicKeyLocation": "/etc/carta/carta_public.pem",
             "privateKeyLocation": "/etc/carta/carta_private.pem",
-            "issuer": "my-carta-server.com"
+            "issuer": "carta.example.com"
         }
     },
     "database": {
@@ -14,15 +14,15 @@
     "serverPort": 8000,
     "serverInterface": "localhost",
     "processCommand": "/usr/bin/carta_backend",
-    "killCommand": "/usr/local/bin/carta-kill-script",
+    "killCommand": "/usr/bin/carta-kill-script",
     "rootFolderTemplate": "/home/{username}",
     "baseFolderTemplate": "/home/{username}",
     "dashboard": {
         "bannerColor": "#d2dce5",
         "backgroundColor": "#f6f8fa",
-        "bannerImage": "/path/to/my/image.svg",
+        "bannerImage": "/usr/lib/node_modules/carta-controller/public/images/carta_logo.svg",
         "infoText": "Welcome to the CARTA server.",
         "loginText": "<span>Please enter your login credentials:</span>",
-        "footerText": "<span>If you have any problems, comments or suggestions, please <a href='mailto:test@test.com'>contact us.</a></span>"
+        "footerText": "<span>If you have any problems, comments or suggestions, please <a href='mailto:admin@carta.example.com'>contact us.</a></span>"
     }
 }

package/config/example_nginx.conf.stub

@@ -1,9 +1,9 @@
 server {
     listen 443 ssl;
     ssl on;
-    server_name my-carta-server.com;
-    ssl_certificate /etc/nginx/ssl/cert.pem; 
-    ssl_certificate_key /etc/nginx/ssl/key.pem;
+    server_name carta.example.com;
+    ssl_certificate /etc/letsencrypt/live/carta.example.com/fullchain.pem; 
+    ssl_certificate_key /etc/letsencrypt/live/carta.example.com/privkey.pem;
     location / {
         proxy_set_header   X-Forwarded-For $remote_addr;
         proxy_pass http://localhost:8000/;
@@ -16,11 +16,8 @@ server {
 }
 
 server {
-    server_name my-carta-server.com;    
-    if ($host = my-carta-server.com) {
-        return 301 https://$host$request_uri;
-    }
+    server_name carta.example.com;    
     listen 80 ;
     listen [::]:80 ;
-    return 404;
+    return 301 https://$host$request_uri;
 }

package/config/example_sudoers_conf.stub

@@ -4,4 +4,4 @@
 carta ALL=(%carta-users) NOPASSWD:SETENV: /usr/bin/carta_backend
 
 # carta user can run the kill script as any user in the carta-users group without entering password
-carta ALL=(%carta-users) NOPASSWD: /usr/local/bin/carta-kill-script
+carta ALL=(%carta-users) NOPASSWD: /usr/bin/carta-kill-script

package/docs/requirements.txt

@@ -1,3 +1,4 @@
 Sphinx==5.1.0
 sphinx-jsonschema==1.19.1
 sphinx-rtd-theme==1.0.0
+sphinx-tabs==3.4.5

package/docs/src/conf.py

@@ -33,6 +33,7 @@ release = '4.1.0'
 extensions = [
     'sphinx_rtd_theme',
     'sphinx-jsonschema',
+    'sphinx_tabs.tabs',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

package/docs/src/configuration.rst

@@ -24,6 +24,8 @@ To provide the ``carta`` user with these privileges, you must make modifications
    :language: cfg
    :name: example_sudoers
 
+Please ensure that the paths to the executables in this file match their install locations on your system (especially if you have installed multiple different versions of the backend or the controller).
+
 .. warning::
     Please only edit your sudoers configuration with ``visudo`` or equivalent.
 
@@ -55,7 +57,7 @@ PAM may be configured to use the host's local UNIX user authentication, or to co
 
 Nginx
 ~~~~~
-    
+
 We strongly suggest serving over HTTPS and redirecting HTTP traffic to HTTPS, especially if handling authentication internally. If you use `nginx <https://www.nginx.com/>`_ as a proxy, you can use `this configuration example <_static/config/example_nginx.conf.stub>`_ as a starting point to redirect incoming traffic from port 443 to port 8000:
 
 .. literalinclude:: _static/config/example_nginx.conf.stub
@@ -89,7 +91,7 @@ By default, the controller assumes the config file is located at ``/etc/carta/co
 
 Configuration may also be added in separate files in a ``config.d`` directory in the same parent directory as the specified config file. Each file in this directory must be a valid configuration file. Any files found will be processed in alphabetical order, after the main configuration file.
 
-The controller automatically executes the backend with the ``--no_http`` flag, to suppress the backend's built-in HTTP server. If the ``logFileTemplate`` configuration option is set, ``--no_log`` is also used to suppress user-level logs. ``--port`` is used to override the default port. ``--top_level_folder`` and a positional argument are used to set the top-level and starting data directories for the user, as specified in the ``rootFolderTemplate`` and ``baseFolderTemplate`` options, respectively. 
+The controller automatically executes the backend with the ``--no_http`` flag, to suppress the backend's built-in HTTP server. If the ``logFileTemplate`` configuration option is set, ``--no_log`` is also used to suppress user-level logs. ``--port`` is used to override the default port. ``--top_level_folder`` and a positional argument are used to set the top-level and starting data directories for the user, as specified in the ``rootFolderTemplate`` and ``baseFolderTemplate`` options, respectively.
 
 To specify additional backend flags, we recommend editing a :ref:`global backend preferences<config-backend>` file. Most commandline arguments to the backend are also recognised as configuration options. The ``additionalArgs`` field in the controller configuration file can be used for any debug options which are not, and to disable the local or global configuration files.
 
@@ -123,9 +125,13 @@ The backend configuration file must adhere to the :ref:`CARTA backend configurat
 .. literalinclude:: _static/config/example_backend.json
    :language: json
    :name: example_backend
-   
+
 .. _test-config:
 
+.. note::
+
+    If you use the global configuration file, please ensure that it is readable by all users in the ``carta-users`` group, *and* that the parent ``/etc/carta/`` directory is readable and executable by all users in the ``carta-users`` group, otherwise the starting backend processes will not be able to access it.
+
 Testing the configuration
 -------------------------
 
@@ -137,7 +143,7 @@ To test the configuration of the controller, you can use the built-in test featu
     Adding additional config file config.d/pam.json
     No top-level folder was specified. Reverting to default location
     Testing configuration with user alice
-    Password for user alice: 
+    Password for user alice:
     ✔ Checked PAM connection for user alice
     ✔ Verified uid (1000) for user alice
     ✔ Generated access token for user alice
@@ -158,4 +164,4 @@ To test the configuration of the controller, you can use the built-in test featu
     Controller tests with user alice succeeded
 
 .. note::
-    If you run the controller from a source directory using ``npm``, use ``--`` to ensure that any commandline parameters are passed to the controller and not to ``npm``. For example: ``npm run start -- --verbose --test alice``.
+    If you run the controller from a source directory using ``npm``, use ``--`` to ensure that any commandline parameters are passed to the controller and not to ``npm``. For example: ``npm start -- --verbose --test alice``.

package/docs/src/index.rst

@@ -8,30 +8,30 @@ CARTA Controller
 
 |backend-github| |npm-package| |last-commit| |commit-activity|
 
-CARTA is the Cube Analysis and Rendering Tool for Astronomy. This document describes the installation and configuration process for the controller component.
+CARTA is the Cube Analysis and Rendering Tool for Astronomy. This document describes the installation and configuration process for a site deployment of CARTA, including the controller and its dependencies. We recommend this deployment option for organisations providing CARTA to multiple users.
 
-Detailed step-by-step instructions are provided for :ref:`Ubuntu 20.04 (Focal Fossa)<focal_instructions>` and :ref:`AlmaLinux 8<almalinux8_instructions>`. 
-We officially support Ubuntu 18.04 and 20.04, and RHEL 7 and 8 (and their freely distributed binary-compatible alternatives, such as CentOS or AlmaLinux), with all available standard updates applied.
+Detailed :ref:`step-by-step instructions <step_by_step>` are provided for a standalone CARTA deployment on a dedicated server. Please use these instructions as a starting point, and make adjustments as required to integrate CARTA into your organisation's existing systems. More detailed information about customisation can be found in the :ref:`installation` and :ref:`configuration` sections.
+
+We officially support Ubuntu 20.04 (v4.x only), 22.04, and 24.04, and AlmaLinux 8 and 9 (and equivalent RPM-based distributions), with all available standard updates applied. We provide legacy support only for existing 4.x installations on RHEL 7 and equivalents.
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
-   
+
    introduction
    installation
    configuration
-   ubuntu_focal_instructions
-   almalinux8_instructions   
+   step_by_step
    schema
    schema_backend
 
-.. |backend-github| image:: https://img.shields.io/badge/CARTA%20Version-4.1.0-brightgreen
+.. |backend-github| image:: https://img.shields.io/badge/CARTA%20Version-5.0.0--beta.1-brightgreen
         :alt: View this backend version on GitHub
-        :target: https://github.com/CARTAvis/carta-backend/releases/tag/v4.1.0
+        :target: https://github.com/CARTAvis/carta-backend/releases/tag/v5.0.0-beta.1
 
-.. |npm-package| image:: https://img.shields.io/npm/v/carta-controller?style=flat
+.. |npm-package| image:: https://img.shields.io/npm/v/carta-controller/beta?style=flat
         :alt: View this project on npm
-        :target: https://npmjs.org/package/carta-controller
+        :target: https://www.npmjs.com/package/carta-controller/v/5.0.0-beta.1
 
 .. |last-commit| image:: https://img.shields.io/github/last-commit/CARTAvis/carta-controller
         :alt: Last commit

package/docs/src/installation.rst

@@ -3,46 +3,218 @@
 Installation
 ============
 
-This section provides a general overview. For a more detailed installation guide, please refer to our step-by-step instructions for :ref:`Ubuntu<focal_instructions>` or :ref:`RPM-based distributions<almalinux8_instructions>`.
+.. note::
+
+    This section provides an overview of different ways to install specific components of CARTA. Please refer to our :ref:`step-by-step instructions <step_by_step>` for a complete set of installation and configuration instructions for supported platforms, and ensure that you have followed all the required steps before running the controller.
 
 .. _install_backend:
 
 Installing the backend
 ----------------------
 
-We provide binary `Ubuntu packages <https://launchpad.net/~cartavis-team/+archive/ubuntu/carta>`_ and `RPM packages <https://copr.fedorainfracloud.org/coprs/cartavis/carta>`_ of the latest beta and stable releases of the CARTA backend. You can install the latest stable version with all dependencies on Ubuntu by adding our PPA to your system and running ``apt-get install carta-backend``.
+Packages
+~~~~~~~~
+
+We provide binary `Ubuntu <https://launchpad.net/~cartavis-team/+archive/ubuntu/carta>`_ and `RPM <https://copr.fedorainfracloud.org/coprs/cartavis/carta>`_ packages of the latest beta and stable releases of the CARTA backend for all officially supported distributions.
+
+You can install the latest stable version with all dependencies on Ubuntu by adding our PPA to your system and running ``apt-get install carta-backend``.
+
+On AlmaLinux you can add our Copr repository and run ``sudo dnf install carta-backend``.
 
 .. note::
 
     The ``carta-backend`` package is updated with every stable CARTA release. If you would like to install the latest **beta** version of CARTA, or to receive beta release updates as well as stable release updates in the future, please install the ``carta-backend-beta`` package instead.
 
-.. note::
+Packaged debug symbols
+~~~~~~~~~~~~~~~~~~~~~~
+
+You can install debugging symbols for our Ubuntu packages with ``apt`` if you enable this option for our PPA.
+
+.. code-block:: shell
+
+    sudo add-apt-repository -c main/debug ppa:cartavis-team/carta
+    sudo apt-get install carta-backend-dbgsym
+
+..
+    From CARTA v5 beta onwards, debugging symbols can also be installed for our RPM packages.
+
+    .. code-block:: shell
+
+        dnf debuginfo-install carta-backend
+
+Rebuilding packages
+~~~~~~~~~~~~~~~~~~~
+
+Our Ubuntu package source is available in `a collection of public repositories <https://github.com/search?q=org%3Aidia-astro+-deb&type=repositories>`_. Please refer to the ``debian`` subdirectories in these repositories if you would like to build your own Debian packages, or to check what build options we use.
+
+You can also obtain the Ubuntu package source with ``apt-src`` (after enabling source packages for our PPA).
+
+.. code-block:: shell
+
+    sudo add-apt-repository -s ppa:cartavis-team/carta
+    sudo apt-get update
+    sudo apt-get install apt-src
+    apt-src install carta-backend
+
+You can obtain the RPM package source with ``dnf``.
+
+.. code-block:: shell
+
+    dnf download --source carta-backend
+
+Custom Casacore version
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The backend depends on a custom version of the Casacore C++ library which also includes the image analysis component of CASA. We provide Ubuntu and RPM packages of this dependency in the same repositories as the backend packages. To avoid clashes with the default system Casacore packages, our packages use a different name, and a custom install location, ``/opt/carta-casacore``.
+
+External data for Casacore
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Casacore depends on a collection of external astronomical data. Some distributions provide packages for this. Because these packages may be far behind the current version of the data, you may wish to manage the required files without using a package.
+
+The ``casacore-data`` package is recommended by the Ubuntu backend package, but installing it is optional. The packages in `our Ubuntu PPA <https://launchpad.net/~cartavis-team/+archive/ubuntu/carta>`_ should be compatible both with the ``casacore-data`` package in the core Ubuntu repositories and with the package provided by the `Kern PPAs <https://launchpad.net/~kernsuite>`_. To avoid installing the ``casacore-data`` package, use the ``--no-install-recommends`` flag when installing the backend package.
+
+An example script for fetching the data manually (you can configure ``cron`` to run this weekly):
+
+.. code-block:: shell
+
+    #!/bin/bash
+
+    rm -f /tmp/WSRT_Measures.ztar
+    wget ftp://ftp.astron.nl/outgoing/Measures/WSRT_Measures.ztar -P /tmp -q
+    tar zxf /tmp/WSRT_Measures.ztar -C /var/lib/casacore/data
+    chmod -R 755 /var/lib/casacore/data
+
+Installing from source
+~~~~~~~~~~~~~~~~~~~~~~
+
+To install the backend on a different host system, or to install a custom version, you can build it from source from the `backend repository <https://github.com/CARTAvis/carta-backend/>`_ on GitHub. The `dockerfiles <https://github.com/CARTAvis/carta-backend/tree/dev/Dockerfiles>`_ in the backend repository are a good starting point for installing and configuring all the build dependencies on different Linux distributions.
+
+Once all dependencies have been installed, check out the backend repository with all its submodules, and build using ``cmake``.
+
+.. code-block:: shell
+
+    # Clone the backend repository
+    git clone --recurse-submodules https://github.com/CARTAvis/carta-backend.git
+    cd carta-backend
+
+    # Configure the build
+    mkdir build
+    cd build
+    cmake ..
 
-    The ``casacore-data`` package is recommended by the Ubuntu backend package, but installing it is optional. The packages in our PPA should be compatible both with the ``casacore-data`` package in the core Ubuntu repositories and with the package provided by the `Kern PPAs <https://launchpad.net/~kernsuite>`_. You may also wish to manage the required data files without using a package.
+    # Build
+    make -j8
 
-To install the backend on a different host system, or to install a custom version, you can build it from source from the `backend repository <https://github.com/CARTAvis/carta-backend/>`_ on GitHub.
+The backend executable will be located in the ``build`` directory.
+
+.. note::
+
+    If you install a custom backend, ensure that a custom ``processCommand`` is set in the controller configuration and that the backend path is updated in the sudoers file.
 
 .. _install_frontend:
 
 Installing the frontend
 -----------------------
 
-If you install the controller from NPM, the corresponding packaged version of the frontend will also be installed automatically. If you wish to install the controller from source, or would like to use a custom frontend version, you can install it from the `frontend repository <https://github.com/CARTAvis/carta-frontend/>`_ on GitHub.
+If you install the controller package from NPM, the corresponding packaged version of the frontend will be installed automatically as a dependency. However, you may wish to install a custom version of the frontend if you are installing the controller from source, or if you would like to test an updated frontend version.
+
+.. note::
+
+    If you install a custom frontend, ensure that a custom ``frontendPath`` is set in the controller configuration.
+
+NPM package
+~~~~~~~~~~~
+
+You can manually install a `specific published version <https://www.npmjs.com/package/carta-frontend>`_ of the frontend `from NPM <https://www.npmjs.com/package/carta-frontend>`_, either globally or into a custom location.
+
+.. code-block:: shell
+
+    # Install latest pre-release version into the current directory
+    npm install carta-frontend@dev
+
+Installing from source
+~~~~~~~~~~~~~~~~~~~~~~
+
+Development versions of the frontend can be installed from the `frontend repository <https://github.com/CARTAvis/carta-frontend/>`_ on GitHub. Node.js and NPM are required for the build. We recommend performing the WebAssembly compilation in a container. The example below requires Docker to be installed. Please refer to the repository documentation for more compilation options.
+
+.. code-block:: shell
+
+    # Clone the frontend repository
+    git clone --recurse-submodules https://github.com/CARTAvis/carta-frontend.git
+    cd carta-frontend
+
+    # Build the frontend (using Docker for WebAssembly compilation)
+    npm install
+    npm run prepack
+
+The built frontend will be available in the ``build`` subdirectory.
+
+Copying existing build
+~~~~~~~~~~~~~~~~~~~~~~
+
+The generated code in the ``build`` directory is standalone and portable between systems. If you already have a build of the frontend in another location, you can safely copy only this directory and use it without having to rebuild it. This may be simpler than setting up a build environment on your server.
+
+The build can be found in ``carta-frontend/build`` in the ``node_packages`` directory created by an NPM install. You can also download tarballs of builds directly from the NPM repository without using ``npm``.
 
 .. _install_controller:
 
 Installing the controller
 -------------------------
 
-You can install the latest stable version of the CARTA controller from NPM by running ``npm install -g carta-controller``, or from GitHub by cloning the `controller repository <https://github.com/CARTAvis/carta-controller/>`_ and running ``npm install``.
+NPM package
+~~~~~~~~~~~
+
+You can install the latest stable version of the CARTA controller from NPM by running ``npm install -g carta-controller``.
 
 .. note::
 
     If you would like to install the latest **beta** release of CARTA, please install ``carta-controller@beta`` instead.
 
+    If you would like to install the package in a local directory, omit the ``-g`` flag.
+
+Installing from source
+~~~~~~~~~~~~~~~~~~~~~~
+
+Development versions of the controller can be installed from the `controller repository <https://github.com/CARTAvis/carta-controller/>`_.
+
+.. code-block:: shell
+
+    # Clone the controller repository
+    git clone https://github.com/CARTAvis/carta-controller.git
+    cd carta-controller
+
+    # Install the controller
+    npm install
+
 .. _run_controller:
 
 Running the controller
 ----------------------
 
-After you have installed the backend and the controller and edited the controller :ref:`configuration<configuration>`, you can start the controller with ``npm run start`` (if installing from the source on GitHub) or just by running ``carta-controller`` (if installing the package from NPM). You can use a utility such as `forever <https://github.com/foreversd/forever>`_ or `pm2 <https://pm2.keymetrics.io/>`_ to keep the controller running. It is also possible to create `a pm2 startup script <https://pm2.keymetrics.io/docs/usage/startup/>`_ which will automatically start the controller when the system is rebooted.
+Executable location
+~~~~~~~~~~~~~~~~~~~
+
+The ``carta-controller`` executable can be found
+
+* on the system path, if you installed the NPM package globally
+* in ``node_modules/.bin`` and ``node_modules/carta-controller/dist``, if you installed the NPM package locally
+* in ``carta-controller/dist``, if you installed from the source directory.
+
+If you installed the controller from source, you can also launch it by running ``npm start`` in the source directory.
+
+Kill script location
+~~~~~~~~~~~~~~~~~~~~
+
+The kill script executable path is
+
+* ``/usr/bin/carta-kill-script`` or ``/usr/local/bin/carta-kill-script``, if you installed the NPM package globally (depending on the Node.js distribution)
+* ``node_modules/.bin/carta-kill-script``, if you installed the NPM package locally
+* ``carta-controller/scripts/carta_kill_script.sh``, if you installed from the source directory.
+
+Ensure that the correct ``killCommand`` is set in the controller configuration, and that the kill script path is correct in the sudoers file.
+
+Persistence
+~~~~~~~~~~~
+
+You can use a utility such as `forever <https://github.com/foreversd/forever>`_ or `pm2 <https://pm2.keymetrics.io/>`_ to keep the controller running. It is also possible to create `a pm2 startup script <https://pm2.keymetrics.io/docs/usage/startup/>`_ which will automatically start the controller when the system is rebooted.

package/docs/src/introduction.rst

@@ -12,13 +12,13 @@ Dependencies
 
 To allow the controller to serve CARTA sessions, you must give it access to an executable CARTA backend, which can be either a compiled executable or a container. If you want to use a non-standard version of the CARTA frontend, you must also build it, and adjust the controller configuration to point to it.
 
-By default, the controller runs on port 8000. It should be run behind a proxy, so that it can be accessed via HTTP and HTTPS. 
+By default, the controller runs on port 8000. It should be run behind a proxy, so that it can be accessed via HTTP and HTTPS.
 
 MongoDB is required for storing user preferences, layouts, workspaces, and (in the near future) controller metrics.
 
 You also need a working `NodeJS LTS <https://nodejs.org/en/about/releases/>`_ installation with NPM. Use ``npm install`` to install all Node dependencies.
 
-Detailed installation instructions are available for :ref:`Ubuntu<focal_instructions>` and :ref:`RPM-based distributions<almalinux8_instructions>`.
+:ref:`Step-by-step installation instructions <step_by_step>` are available for officially supported platforms.
 
 .. _authentication: