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.


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.0.0-beta.1 tag of the 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 installation with NPM. Use npm install to install all Node dependencies.

Authentication support

The CARTA controller supports four modes for authentication. All four modes use refresh and access tokens, as described in the OAuth2 Authorization flow, stored in JWT format. The modes are:

  • PAM authentication: The PAM interface of the host system is used for user authentication. After the user’s username and password configuration are validated by PAM, 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.

  • LDAP authentication: As above, but an LDAP server is used directly for user authentication.

  • 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.

Getting help

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.

Future work

Features still to be implemented:

  • Better error feedback

  • More flexibility with external auth