Unify stable and beta release instructions and fix some issues (#164)

* Unify stable and beta release instructions and fix some issues

* Fixed incorrect beta location in /opt

* Mention COPR in general installation section

* fixed url format

* mention workspaces

docs/src/almalinux8_instructions.rst

@@ -54,7 +54,10 @@ The CARTA controller uses `MongoDB <https://www.mongodb.com/>`_ to store user pr
 .. note::
 
     On RHEL7/CentOS7, MongoDB v14 can be installed as follows:
-    ``curl -fsSL https://rpm.nodesource.com/setup_14.x | bash - && yum install -y nodejs``
+    
+    .. code-block:: shell
+    
+        curl -fsSL https://rpm.nodesource.com/setup_14.x | bash - && yum install -y nodejs
 
 
 3. Install the CARTA controller
@@ -66,6 +69,15 @@ The easiest way to install the CARTA controller is using ``npm``.
 
     sudo dnf install -y python3 make gcc-c++
     sudo npm install -g --unsafe-perm carta-controller
+    
+    
+.. note::
+
+    If you would like to install the latest **beta** release of CARTA, please install the ``beta`` tag of the controller instead:
+    
+    .. code-block:: shell
+    
+        sudo npm install -g --unsafe-perm carta-controller@beta
 
 .. note::
 
@@ -98,8 +110,22 @@ The easiest way is to install the CARTA backend is from our `cartavis/carta Copr
     sudo dnf -y install carta-backend
 
     # Check that the backend can run and matches the major version number of the controller.
-    # Please note, we currently install the version of carta_backend in a non-standard location.
-    /opt/carta/bin/carta_backend --version
+    /usr/bin/carta_backend --version
+
+.. 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 ``carta-backend-beta`` instead:
+    
+    .. code-block:: shell
+    
+        sudo dnf -y install carta-backend-beta
+    
+    Make sure that you install the matching controller version (using the ``beta`` tag).
+
+    We currently install the beta version of ``carta_backend`` in a non-standard location:
+    
+    .. code-block:: shell
+    
+        /opt/carta-beta/bin/carta_backend --version
 
 
 5. Install Nginx
@@ -163,11 +189,11 @@ An :ref:`example sudoers configuration<example_sudoers>` is provided in the conf
     The ``carta`` user should not be in the ``carta-users`` group. ``carta-users`` should only be assigned to the normal user accounts.
 
 .. note::
-    As we install the version of the carta_backend in a non-standard location, please remember to change the path to the carta_backend executable in the custom sudoers file:
-
-   .. code-block:: bash
-
-      carta ALL=(%carta-users) NOPASSWD:SETENV: /opt/carta/bin/carta_backend
+    If you have installed the **beta** version of CARTA, please remember to change the path to the ``carta_backend`` executable in the sudoers file:
+    
+    .. code-block:: bash
+    
+        carta ALL=(%carta-users) NOPASSWD:SETENV: /opt/carta-beta/bin/carta_backend
 
 7. Set up the user authentication method
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/src/installation.rst

@@ -3,16 +3,22 @@
 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>`.
+
 .. _install_backend:
 
 Installing the backend
 ----------------------
 
-We provide `binary Ubuntu packages <https://launchpad.net/~cartavis-team/+archive/ubuntu/carta>`_ of the latest beta and release versions of the CARTA backend. 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.
+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``.
+
+.. 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::
 
-    The ``casacore-data`` package is recommended by the 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.
+    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.
 
 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.
 
@@ -28,7 +34,11 @@ If you install the controller from NPM, the corresponding packaged version of th
 Installing the controller
 -------------------------
 
-You can install the latest release 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``.
+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``.
+
+.. note::
+
+    If you would like to install the latest **beta** release of CARTA, please install ``carta-controller@beta`` instead.
 
 .. _run_controller:
 

docs/src/introduction.rst

@@ -10,14 +10,16 @@ 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 ``v4.1.0`` 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.
 
 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 and (in the near future) controller metrics.
+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>`.
+
 .. _authentication:
 
 Authentication support

docs/src/ubuntu_focal_instructions.rst

@@ -25,6 +25,17 @@ Install the CARTA backend and other required packages
     # Install additional packages
     sudo apt-get install nginx g++ mongodb make curl
 
+.. 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:
+
+    .. code-block:: shell
+    
+        sudo apt-get install install carta-backend-beta
+    
+    These packages cannot be installed simultaneously, as they use the same install locations. If you install one, you will automatically be prompted to uninstall the other.
+
+    Make sure that you install the matching controller version (using the ``beta`` tag).
+
 Set up directories and permissions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -87,6 +98,14 @@ Install CARTA controller
     openssl genrsa -out carta_private.pem 4096
     openssl rsa -in carta_private.pem -outform PEM -pubout -out carta_public.pem
     
+.. note::
+
+    If you would like to install the latest **beta** release of CARTA, please install the ``beta`` tag of the controller instead:
+
+    .. code-block:: shell
+    
+        sudo npm install -g --unsafe-perm carta-controller@beta
+    
 Configure controller
 ~~~~~~~~~~~~~~~~~~~~