carta-node-server v1.4.1

CARTA Server

Work in progress, documentation still under construction

Introduction

The CARTA server 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 server can either handle authentication itself, or delegate it to an external OAuth2-based authentication server.

Dependencies

To allow the server to serve CARTA sessions, you must give it access to an executable CARTA backend, which can be either a compiled executable or a container. You must also build the CARTA frontend, and adjust the server configuration to point to it. You should use the dev branch of carta-backend. and the dev branch of carta-frontend.

By default, the server 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) server metrics. You also need a working NodeJS LTS installation with NPM. Use npm install to install all Node dependencies.

Authentication support

The CARTA server supports three modes for authentication. All three modes use refresh and access tokens, as described in the OAuth2 Authorization flow, stored in JWT 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-node-server 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. 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:

openssl genrsa -out carta_private.pem 4096
openssl rsa -in carta_private.pem -outform PEM -pubout -out carta_public.pem

Server Configuration

Server configuration is handled by a configuration file in JSON format, adhering to the CARTA config schema. Additional details can be found in the auto-generated config documentation or the example config. By default, the server 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 server.

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, which is watched by the server and reloaded whenever it is updated.

System Configuration

The user under which the CARTA server 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 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. An example sudoers config 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 as a proxy, you can use this configuration example 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 server 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 server

• Build carta-backend using the dev branch (or create the appropriate container)
• Configure and build carta-frontend using the angus/database_service branch
• Edit the server 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 frontend and backend and edited the server configuration, you can start the server with npm run start. You can use a utility such as forever or pm2 to keep the server running by restarting it automatically.

Getting help

If you encounter a problem with the server or documentation, please submit an issue in this repo. If you need assistance in configuration or deployment, please contact the CARTA helpdesk.

TODO

Still to be implemented:

• Better error feedback
• More flexibility with external auth
• Integration with a CARTA frontend npm package