Merge pull request #54 from CARTAvis/confluence/update-instructions-1.4

Backport of documentation changes to 1.4

.gitignore

@@ -3,4 +3,5 @@
 node_modules/*
 dist/*.js
 dist/*.js.map
-carta-controller-*.tgz
+carta-controller-*.tgz
+docs/_build

README.md

@@ -4,74 +4,8 @@
 ![last commit](https://img.shields.io/github/last-commit/CARTAvis/carta-controller)
 ![commit activity](https://img.shields.io/github/commit-activity/m/CARTAvis/carta-controller)
 
-## Introduction
-
 The CARTA controller provides a simple dashboard which authenticates users and allows them to manage their CARTA backend processes. It also serves static frontend code to clients, and dynamically redirects authenticated client connections to the appropriate backend processes. The controller can either handle authentication itself, or delegate it to an external OAuth2-based authentication server.
 
-## 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 `v1.4.0` tag of [`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. 
-
-MongoDB is required for storing user preferences, layouts and (in the near future) controller metrics. You also need a working [NodeJS LTS](https://github.com/nvm-sh/nvm#long-term-support) installation with NPM. Use `npm install` to install all Node dependencies.
-
-## Installation
-
-You can install the CARTA controller from NPM by running `npm install -g carta-controller` and then running `carta-controller`.
-You can also install the controller from GitHub by cloning this repository, running `npm install` and then `npm run start`.
-
-## Authentication support
-
-The CARTA controller supports three modes for authentication. All three modes use refresh and access tokens, as described in the [OAuth2 Authorization flow](https://tools.ietf.org/html/rfc6749#section-1.3.1), stored in [JWT](https://jwt.io/) format. The modes are:
-- **LDAP-based authentication**: An existing LDAP server is used for user authentication. After the user's username and password configuration are validated by the LDAP server, `carta-controller` returns a long-lived refresh token, signed with a private key, which can be exchanged by the CARTA dashboard or the CARTA frontend client for a short-lived access token.
-- **Google authentication**: Google's authentication libraries are used for handling authentication. You must create a new web application in the [Google API console](https://console.developers.google.com/apis/credentials). You will then use the  client ID provided by this application in a number of places during the configuration.
-- **External authentication**: This allows users to authenticate with some external OAuth2-based authentication system. This requires a fair amount of configuration, and has not been well-tested. It is assumed that the refresh token passed by the authentication system is stored as an `HttpOnly` cookie.
-
-You can generate a private/public key pair in PEM format using `openssl`:
-```shell script
-openssl genrsa -out carta_private.pem 4096
-openssl rsa -in carta_private.pem -outform PEM -pubout -out carta_public.pem
-```
-
-## Controller Configuration
-Controller configuration is handled by a configuration file in JSON format, adhering to the [CARTA config schema](config/config_schema.json). Additional details can be found in the auto-generated config documentation in the `docs` folder, or the [example config](config/example_config.json). 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. 
-
-For external authentication systems, you may need to translate a unique ID (such as email or username) from the authenticated user information to the system user. You can do this by providing a [user lookup table](config/usertable.txt.stub), which is watched by the controller and reloaded whenever it is updated.
-
-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.
-
-## System Configuration
-
-The user under which the CARTA controller is running (assumed to be `carta`) must be given permission to use `sudo` to start `carta_backend` processes as any authenticated user and stop running `carta_backend` processes belonging to authenticated users. We provide a [kill script](scripts/carta_kill_script.sh) which is only able to kill processes matching the name `carta_backend`. This makes it possible to restrict what processes the `carta` user is permitted to kill.
-
-To provide the `carta` user with these privileges, you must make modifications to the [sudoers configuration](https://www.sudo.ws/man/1.9.0/sudoers.man.html). An [example sudoers config](config/example_sudoers_conf.stub) is provided. This example allows the `carta` user to run `carta_backend` only as users belonging to a specific group (assumed to be `carta-users`), in order to deny access to unauthorized accounts.
-
-**Please only edit your sudoers configuration with `visudo` or equivalent.**
-
-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](config/example_nginx.conf.stub) as a starting point to redirect incoming traffic from port 443 to port 8000.
-
-You can also use other HTTP servers, such as Apache. Please ensure that they are set up to forward both standard HTTP requests and WebSocket traffic to the correct port.
-
-By default, the controller attempts to write log files to the `/var/log/carta` directory. Please ensure that this directory exists and that the `carta` user has write permission.
-
-## Running the controller
-
-- Checkout and build [carta-backend](https://github.com/CARTAvis/carta-backend) using the `v1.4.0` tag (or create the appropriate container). Detailed instructions for Ubuntu 20.04 are available [here](docs/ubuntu_focal_detailed_install.md).
-- Edit the controller configuration file at `/etc/carta/config.json`
-- Perform system configuration:
-    - Ensure `/var/log/carta` exists and is writeable by the appropriate user    
-    - Adjust the sudoers configuration
-    - Redirect traffic to port 8000
-
-After you have built the backend and edited the controller configuration, you can start the controller with `npm run start` (if cloning from the git repository) or just running `carta-controller` (if installing 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.
-
-## Getting help
-
-If you encounter a problem with the controller or documentation, please submit an issue in this repo. If you need assistance in configuration or deployment, please contact the [CARTA helpdesk](mailto:carta_helpdesk@asiaa.sinica.edu.tw).
-
-## TODO
+For installation and configuration instructions, and more detailed information about the controller's features, please consult [the full documentation on ReadTheDocs](https://carta-controller.readthedocs.io/en/1.4/).
 
-Still to be implemented:
-- Better error feedback
-- More flexibility with external auth
+If you encounter a problem with the controller or documentation, please submit an issue in the controller repo. If you need assistance in configuration or deployment, please contact the [CARTA helpdesk](mailto:carta_helpdesk@asiaa.sinica.edu.tw).

config/config_schema.json

@@ -1,5 +1,5 @@
 {
-    "$id": "https://example.com/person.schema.json",
+    "$id": "carta_config",
     "$schema": "http://json-schema.org/draft-07/schema#",
     "title": "CARTA configuration schema",
     "description": "Schema defining configuration options for the CARTA server",
@@ -459,4 +459,4 @@
             }
         }
     }
-}
+}

config/example_config.json

@@ -16,7 +16,7 @@
         "databaseName": "CARTA"
     },
     "serverAddress": "https://my-carta-server.com",
-    "processCommand": "/usr/local/bin/carta_backend",
+    "processCommand": "/usr/bin/carta_backend",
     "killCommand": "/usr/local/bin/carta_kill_script.sh",
     "rootFolderTemplate": "/home/{username}",
     "baseFolderTemplate": "/home/{username}",
@@ -28,4 +28,4 @@
         "loginText": "<span>Click <b>Sign in</b> to log in via Google.</span>",
         "footerText": "<span>If you would like to access the CARTA server, or have any problems, comments or suggestions, please <a href='mailto:test@test.com'>contact us.</a></span>"
     }
-}
+}

config/example_sudoers_conf.stub

@@ -1,7 +1,7 @@
-# customise this file to fit your environment using visudo /etc/sudoers.d/carta_server
+# customise this file to fit your environment using visudo /etc/sudoers.d/carta_controller
 
 # carta user can run the carta_backend command as any user in the carta-users group without entering password
-carta ALL=(%carta-users) NOPASSWD:SETENV: /usr/local/bin/carta_backend
+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.sh
+carta ALL=(%carta-users) NOPASSWD: /usr/local/bin/carta_kill_script.sh

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = src
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)