carta-controller 3.0.0-beta.1d → 3.0.0-dev.20220301

package/docs/src/configuration.rst

@@ -8,7 +8,7 @@ Configuration
 System Configuration
 --------------------
 
-.. _config-backend:
+.. _config-backend-permissions:
 
 CARTA backend permissions
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -68,10 +68,10 @@ By default, the controller attempts to write log files to the ``/var/log/carta``
 
 .. _config-controller:
 
-Controller Configuration
+Controller configuration
 ------------------------
 
-Controller configuration is handled by a configuration file in JSONC (JSON with JavaScript style comments) format, adhering to the :ref:`CARTA configuration schema<schema>`. An `example configuration file <_static/config/example_config.json>`_ is provided:
+Controller configuration is handled by a configuration file in JSONC (JSON with JavaScript style comments) format, adhering to the :ref:`CARTA controller configuration schema<schema>`. An `example controller configuration file <_static/config/example_config.json>`_ is provided:
 
 .. literalinclude:: _static/config/example_config.json
    :language: json
@@ -79,7 +79,11 @@ Controller configuration is handled by a configuration file in JSONC (JSON with
 
 By default, the controller assumes the config file is located at ``/etc/carta/config.json``, but you can change this with the ``--config`` or ``-c`` command line argument when running the controller.
 
-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. Additional backend flags may be specified with ``additionalArgs``.
+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. 
+
+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.
 
 If you use an external :ref:`authentication<authentication>` system, you may need to translate a unique ID (such as email or username) from the authenticated external user information to an internal system user. You can do this by providing a `user lookup table <_static/config/usertable.txt.stub>`_, which is watched by the controller and reloaded whenever it is updated:
 
@@ -87,3 +91,53 @@ If you use an external :ref:`authentication<authentication>` system, you may nee
    :language: cfg
 
 You can alter the controller's dashboard appearance by adjusting the ``dashboard`` field in the config file. You can change the banner image and background, and add login instructions or institutional notices.
+
+The ``httpOnly`` flag can be used to disable secure signing of authentication tokens. This should only be used during initial deployment and testing, or debugging.
+
+.. _config-backend:
+
+Backend configuration
+---------------------
+
+The global configuration file for the CARTA backend is located at ``/etc/carta/backend.json``. A per-user configuration file can also be placed in each user's local CARTA preferences directory (typically ``.carta`` or ``.carta-beta`` in the user's home directory, depending on how the CARTA backend was installed). On a multi-user system, if users have write access to this location, you may wish to disable the use of per-user configuration files, to prevent users from bypassing the root directory configuration set by the controller. This must be done through the ``additionalArgs`` field in the :ref:`controller configuration<config-controller>`.
+
+The backend configuration file must adhere to the :ref:`CARTA backend configuration schema<schema_backend>`. An `example backend configuration file <_static/config/example_backend.json>`_ is provided:
+
+.. literalinclude:: _static/config/example_backend.json
+   :language: json
+   :name: example_backend
+   
+.. _test-config:
+
+Testing the configuration
+-------------------------
+
+To test the configuration of the controller, you can use the built-in test feature. Run ``carta-controller --verbose --test <username>`` as the ``carta`` user (or whichever user has the :ref:`added sudoers permissions<config-backend-permissions>`). ``<username>`` should be a user in the ``carta-users`` group. The expected output looks like this:
+
+.. code-block::
+
+    Checking config file /etc/carta/config.json
+    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: 
+    ✔ Checked PAM connection for user alice
+    ✔ Verified uid (1000) for user alice
+    ✔ Generated access token for user alice
+    ✔ Checked database connection
+    ✔ Checked log writing for user alice
+    ✔ Read frontend index.html from /custom/frontend/path/build
+    [
+    'running sudo --preserve-env=CARTA_AUTH_TOKEN -n -u alice /usr/bin/carta_backend --no_http --debug_no_auth --port 3499 --top_level_folder /usr/share/carta --no_log /usr/share/carta'
+    ]
+    [2021-11-30 12:28:48.207] [info] /usr/bin/carta_backend: Version 3.0.0-beta.2
+    [2021-11-30 12:28:48.209] [info] Listening on port 3499 with top level folder /usr/share/carta, starting folder /usr/share/carta. The number of OpenMP worker threads will be handled automatically.
+    ✔ Backend process started successfully
+    [2021-11-30 12:28:50.169] [info] Session 1 [127.0.0.1] Connected. Num sessions: 1
+    ✔ Backend process accepted connection
+    [ 'running sudo -u alice ./scripts/carta_kill_script.sh 54275' ]
+    ✔ Backend process killed correctly
+    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``.

package/docs/src/index.rst

@@ -10,7 +10,8 @@ CARTA Controller
 
 CARTA is the Cube Analysis and Rendering Tool for Astronomy. This document describes the installation and configuration process for the controller component.
 
-Detailed :ref:`step-by-step instructions<focal_instructions>` are provided for Ubuntu 20.04 (Focal Fossa).
+Detailed step-by-step instructions are provided for :ref:`Ubuntu 20.04 (Focal Fossa)<focal_instructions>` and :ref:`CentOS 8<centos8_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.
 
 .. toctree::
    :maxdepth: 2
@@ -20,13 +21,15 @@ Detailed :ref:`step-by-step instructions<focal_instructions>` are provided for U
    installation
    configuration
    ubuntu_focal_instructions
+   centos8_instructions   
    schema
+   schema_backend
 
-.. |backend-github| image:: https://img.shields.io/badge/CARTA%20Version-3.0.0--beta.1c-brightgreen
+.. |backend-github| image:: https://img.shields.io/badge/CARTA%20Version-3.0.0--beta.2-brightgreen
         :alt: View this backend version on GitHub
-        :target: https://github.com/CARTAvis/carta-backend/releases/tag/v3.0.0-beta.1c
+        :target: https://github.com/CARTAvis/carta-backend/releases/tag/v3.0.0-beta.2
 
-.. |npm-package| image:: https://img.shields.io/npm/v/carta-controller/dev.svg?style=flat
+.. |npm-package| image:: https://img.shields.io/npm/v/carta-controller/beta.svg?style=flat
         :alt: View this project on npm
         :target: https://npmjs.org/package/carta-controller
 

package/docs/src/installation.rst

@@ -8,7 +8,7 @@ Installation
 Installing the backend
 ----------------------
 
-We provide `binary Debian packages <https://launchpad.net/~cartavis-team/+archive/ubuntu/carta>`_ of the latest development and release versions of the CARTA backend for Ubuntu 20.04 (Focal Fossa) and Ubuntu 18.04 (Bionic Beaver). You can install the development version with all dependencies by adding our PPA to your system and running ``apt-get install carta-backend-beta``. Please refer to our :ref:`Ubuntu Focal instructions<focal_instructions>` for more details.
+We provide `binary Debian packages <https://launchpad.net/~cartavis-team/+archive/ubuntu/carta>`_ of the latest beta and release versions of the CARTA backend for Ubuntu 20.04 (Focal Fossa) and Ubuntu 18.04 (Bionic Beaver). You can install the beta version with all dependencies by adding our PPA to your system and running ``apt-get install carta-backend-beta``. Please refer to our :ref:`Ubuntu Focal instructions<focal_instructions>` for more details.
 
 .. note::
 
@@ -28,7 +28,7 @@ If you install the controller from NPM, the corresponding packaged version of th
 Installing the controller
 -------------------------
 
-You can install the development version of the CARTA controller from NPM by running ``npm install -g carta-controller@dev``, or from GitHub by cloning the `controller repository <https://github.com/CARTAvis/carta-controller/>`_ and running ``npm install``.
+You can install the beta version of the CARTA controller from NPM by running ``npm install -g carta-controller@beta``, or from GitHub by cloning the `controller repository <https://github.com/CARTAvis/carta-controller/>`_ and running ``npm install``.
 
 .. _run_controller:
 

package/docs/src/introduction.rst

@@ -10,7 +10,7 @@ The CARTA controller provides a simple dashboard which authenticates users and a
 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. You should use the ``v3.0.0-beta.1c`` tag of `the CARTA backend <https://github.com/CARTAvis/carta-backend>`_.
+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. You should use the ``v3.0.0-beta.2`` tag of `the CARTA backend <https://github.com/CARTAvis/carta-backend>`_.
 
 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. 
 

package/docs/src/schema_backend.rst

@@ -0,0 +1,7 @@
+.. _schema_backend:
+
+.. jsonschema:: _static/config/preference_backend_schema_2.json
+    :lift_description:
+    :lift_definitions:
+    :auto_target:
+    :auto_reference:

package/docs/src/ubuntu_focal_instructions.rst

@@ -19,7 +19,7 @@ Install the CARTA backend and other required packages
     sudo add-apt-repository ppa:cartavis-team/carta
     sudo apt-get update
 
-    # Install the development backend package with all dependencies
+    # Install the beta backend package with all dependencies
     sudo apt-get install carta-backend-beta
     
     # Install additional packages
@@ -74,7 +74,7 @@ Install CARTA controller
     sudo apt-get install -y nodejs build-essential
 
     # Install carta-controller (includes frontend config)
-    sudo npm install -g --unsafe-perm carta-controller@dev
+    sudo npm install -g --unsafe-perm carta-controller@beta
     
     # Install PM2 node service
     sudo npm install -g pm2

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "carta-controller",
-    "version": "3.0.0-beta.1d",
+    "version": "3.0.0-dev.20220301",
     "description": "NodeJS-based controller for CARTA",
     "repository": "https://github.com/CARTAvis/carta-controller",
     "homepage": "https://www.cartavis.org",
@@ -23,8 +23,8 @@
         "ajv": "^8.2.0",
         "ajv-formats": "^2.1.0",
         "body-parser": "^1.19.0",
-        "carta-frontend": "^3.0.0-beta.1c",
-        "chalk": "^4.1.1",
+        "carta-frontend": "^3.0.0-dev.20220222",
+        "chalk": "^4.1.2",
         "compression": "^1.7.4",
         "cookie-parser": "^1.4.5",
         "cors": "^2.8.5",

package/public/dashboard.js

@@ -25,7 +25,7 @@ apiCall = async (callName, jsonBody, method, authRequired) => {
     const options = {
         method: method || "get"
     };
-    if (jsonBody) {
+    if (method !== "get" && jsonBody) {
         options.body = JSON.stringify(jsonBody);
         options.headers = {"Content-Type": "application/json"}
     } else {
@@ -103,7 +103,7 @@ setButtonDisabled = (elementId, disabled) => {
 updateServerStatus = async () => {
     let hasServer = false;
     try {
-        const res = await apiCall("server/status", undefined, "get", true);
+        const res = await apiCall("server/status", {}, "get", true);
         if (res.ok) {
             const body = await res.json();
             if (body.success && body.running) {

package/views/templated.pug

@@ -25,7 +25,7 @@ html
                     .spacer
                     img(src="dashboard/images/carta_logo.svg" alt="carta_logo")
                     .titletext
-                        | CARTA 3.0.0-beta.1c
+                        | CARTA 3.0.0-beta.2
                         br
                         span(style="font-size: 13px; font-weight: lighter") Cube Analysis and Rendering Tool for Astronomy
                         br