Step-by-step instructions for a complete deployment

Overview

Note

These instructions aim to be a complete guide for installing CARTA for multiple users on a dedicated server, with authentication of local users via PAM, and other simple suggested defaults. If you are integrating CARTA into an existing system, you may need to adjust some of these steps. Please refer to the more detailed Installation and Configuration instructions for more options.

Note

CARTA version 5.x is supported on Ubuntu 22.04 (Jammy Jellyfish) and 24.04 (Noble Numbat). The Ubuntu instructions should also work on equivalent Ubuntu-based distributions, and may work with some adjustments on other Debian-based distributions and non-LTS Ubuntu releases.

Prerequisites

These instructions assume that you are logged in as an ordinary user with passwordless sudo access. Ubuntu server images have a default ubuntu user configured with these privileges. On AlmaLinux this user is called almalinux.

We assume that your shell is bash. curl and vim must be installed.

sudo apt-get install vim curl

We include instructions for configuring SSL in your webserver. This requires either a domain name and certificates provided by your organisation, or a domain from a provider compatible with Let’s Encrypt (or your preferred certificate authority). Domain name setup is outside the scope of this document.

Install dependencies

Install MongoDB

We recommend installing the Community Edition Debian package of MongoDB on all supported Ubuntu versions.

# Import public key for MongoDB repo
curl -fsSL https://www.mongodb.org/static/pgp/server-8.0.asc | sudo gpg -o /usr/share/keyrings/mongodb-server-8.0.gpg --dearmor

# Add MongoDB repository
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] https://repo.mongodb.org/apt/ubuntu $(lsb_release -cs)/mongodb-org/8.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list

sudo apt-get update

# Install MongoDB
sudo apt-get install mongodb-org

# Start MongoDB
sudo systemctl start mongod

# Make MongoDB start automatically on system restart
sudo systemctl enable mongod

Please refer to the detailed MongoDB installation instructions for more information.

Install CARTA backend and other required packages

Ubuntu packages for CARTA components are available from our Launchpad PPA.

# Add CARTA PPA
sudo add-apt-repository ppa:cartavis-team/carta
sudo apt-get update

# Install the backend package with all dependencies
sudo apt-get install carta-backend

# Install additional packages
sudo apt-get install g++ make build-essential libpam0g-dev

Note

The packages in the main PPA are 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 use the alternate preview PPA instead:

# Add CARTA preview PPA
sudo add-apt-repository ppa:cartavis-team/carta-preview
sudo apt-get update

Multiple versions of the backend package and its CASA dependency cannot be installed simultaneously. If you would like to install the release and beta backends in parallel on the same system, we recommend that you use containers.

Make sure that you install the matching controller version (using the beta tag).

Install Node.js

We recommend installing the latest LTS version of Node.js (currently v22) from the NodeSource repository. The minimum version required for CARTA 5.x is v20.

# Install the latest Node.js LTS repo
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

# Install Node.js (includes NPM)
sudo apt-get install nodejs

Install CARTA controller

# Install carta-controller (includes frontend dependency)
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:

sudo npm install -g --unsafe-perm carta-controller@beta

Note

Do not pass the --unsafe-perm flag to npm if using a custom installation of Node.js in a local directory.

System configuration

Set up users and directories

All users who should have access to CARTA must belong to a group that identifies them (assumed here to be called carta-users).

For security reasons, we do not recommend running the CARTA controller as the root user. Instead, create a dedicated user called carta for this purpose. The carta user should not be added to the carta-users group.

# Create a group to identify CARTA users
sudo groupadd carta-users

# Create a 'carta' user to run the controller
sudo useradd --system --create-home --home /var/lib/carta --shell=/bin/bash --user-group carta

# Create a log directory owned by carta
sudo mkdir -p /var/log/carta
sudo chown carta: /var/log/carta

# Create a config directory owned by carta
sudo mkdir -p /etc/carta
sudo chown carta: /etc/carta

Set up permissions

Warning

If you are using PAM authentication of local users, the carta user needs read access to the shadow file. This step is not required if you are configuring a different form of user authentication (e.g. LDAP).

On Ubuntu by default the shadow file is group-owned by a shadow group which has read access. You only have to add the carta user to the group.

# Add 'carta' user to the shadow group
sudo usermod -a --groups shadow carta

The carta user must be given permission to execute the CARTA backend and the script to kill the CARTA backend on behalf of CARTA users using sudo without providing a password.

# Edit sudoers file to grant 'carta' user permission to execute
# the backend and kill script as any user in `carta-users` group
sudo visudo -f /etc/sudoers.d/carta_controller

An example sudoers configuration is provided in the configuration section. Make sure that the paths to the two executables in the file match their install locations on your system.

Configure webserver

Install and configure Nginx

The CARTA controller requires a webserver. We provide instructions for Nginx.

# Install Nginx
sudo apt-get install nginx

Note

If you have also installed a firewall on your server, ensure that it allows both HTTP and HTTPS traffic.

Configure SSL

For security reasons, we strongly recommend configuring SSL on your server and redirecting all HTTP traffic to HTTPS. We provide instructions for obtaining certificates from Let’s Encrypt using the Certbot tool. Certbot will automatically renew your certificates for you. If your organisation can provide you with certificates for your domain, you can skip this step.

Note

Let’s Encrypt only issues certificates for publically resolvable domain names, so make sure that you have configured DNS appropriately before this point, and that Nginx is already running and serving its default index page over HTTP at your public domain.

# Install certbot
sudo apt-get install certbot python3-certbot-nginx

# Run certbot and follow the prompts to generate the certificates
# Note the certificate and key locations which are printed out
sudo certbot certonly --nginx

Note

For simplicity we have provided instructions for installing Certbot from the Ubuntu repositories with apt. However, these packages are far behind the latest version, particularly in older Ubuntu releases. The official instructions recommend installation via snap.

Once you have obtained the certificates, edit the Nginx configuration. A sample configuration file is provided in the configuration section. Adjust the paths to the certificate and the certificate key, using the paths printed by certbot in the previous step.

# Create an Nginx configuration file for CARTA
sudo vim /etc/nginx/conf.d/carta.conf

# Restart Nginx
sudo systemctl restart nginx

Configure CARTA controller

Basic configuration

These configuration steps should be performed as the carta user. This user should own all the files in the /etc/carta directory.

The CARTA controller uses SSL keys for authentication.

# Switch to carta user
sudo su - carta

# Generate private/public keys
openssl genrsa -out /etc/carta/carta_private.pem 4096
openssl rsa -in /etc/carta/carta_private.pem -outform PEM -pubout -out /etc/carta/carta_public.pem

Edit /etc/carta/config.json to customise the appearance of the dashboard and other controller options. We recommend configuring options for the backend in a separate /etc/carta/backend.json file. We provide sample controller and backend configuration files. Please refer to the Configuration instructions for more details.

# Create a controller configuration file
vim /etc/carta/config.json

# Create a global backend configuration file
vim /etc/carta/backend.json

Note

If you use /etc/carta/backend.json, please ensure that it is readable by all users in the carta-users group, and that /etc/carta/ is readable and executable by these users.

Test CARTA controller

To test that the controller is configured correctly, use the built-in test feature. You will need at least one user in the carta-users group.

# Switch back to user with sudo access
exit

# Create a test user in the 'carta-users' group
sudo useradd --create-home --groups carta-users alice
sudo passwd alice

# Switch to 'carta' user
sudo su - carta

# Run the controller test
carta-controller --verbose --test alice

Please refer to the detailed configuration instructions for more information about the test feature.

Start CARTA controller

# Switch back to user with sudo access
exit

# Copy test image to user's home directory
sudo cp /usr/share/carta/default.fits /home/alice/test.fits
sudo chown alice: /home/alice/test.fits

# Switch to carta user
sudo su - carta

carta-controller

You should now be able to navigate to your domain, log into CARTA with your test user’s credentials, and open and view the test image.

Note

In the example above, the default test image packaged with the CARTA backend is copied into the test user’s home directory – if you configured a different user directory structure, or installed a custom backend, please adjust these paths.

Configure autostart

The PM2 service will start the controller automatically after a reboot.

# Switch to user with sudo access
exit

# Install PM2 process manager
sudo npm install -g pm2

# Switch to carta user
sudo su - carta

# Generate startup script
pm2 startup

# Switch back to user with sudo privileges
exit

# Execute the output of the 'pm startup' command

# Switch back to the 'carta' user
sudo su - carta

# Start the controller
pm2 start carta-controller

# Save the running process
pm2 save

Please refer to the PM2 documentation for more detailed instructions.

Clean up

Once you have finished testing the controller, remove the test user.

sudo userdel --remove alice