System configuration#

This guide covers common system-wide configuration tasks for an OrangeQS Juice installation: adding user accounts, registering services, provisioning InfluxDB buckets, and installing Python packages for every user and service. These all involve editing files under /etc/juice/config and re-running juice install, so they require sudo/root access on the host system.

Adding users#

By default, a production environment of OrangeQS Juice is configured to use the host Unix system for user authentication. This means that any user account present on the host system can log in to the Juice interface. Thus, you can add users by creating Unix users using the useradd and passwd commands. After adding a user, you should restart your Jupyterhub service for the changes to take effect.

Below is an example of creating a user account for Juno and restarting JupyterHub:

# Add the user "juno" and set a password.
sudo useradd -m juno
sudo passwd juno

# Restart JupyterHub for the changes to take effect.
sudo systemctl restart juice-jupyterhub

Adding services#

The main Juice configuration is stored in orchestration.toml. As an example, we will add a new service called "<service_name>". To add this service, add the following to the configuration file stored at /etc/juice/config/orchestration.toml:

[services."<service_name>"]
# No configuration options yet.

Note that this can only be done by a system administrator with root privileges. After adding the new service, run the following command from the host system terminal to apply the changes:

sudo juice install --restart

After the command completes, you should see the new service listed in the OrangeQS Juice interface.

Configuration reference

For more information on configuring OrangeQS Juice refer to the Configuration reference.

Adding InfluxDB buckets#

OrangeQS Juice comes shipped with InfluxDB, a time-series database. The InfluxDB buckets are configured using orchestration.toml::influxdb2.buckets. To add a new InfluxDB bucket add the following to the configuration file stored at /etc/juice/config/orchestration.toml:

[influxdb2.buckets."<bucket_name>"]
# The name of the bucket must match with the name above.
name = "<bucket_name>"
# Optional: how long to retain data in this bucket (e.g., "30d" for 30 days)
# Defaults to "0s", which means data is retained forever.
retention = "30d"

After adding the new bucket, run the following command form the host system terminal to apply the changes:

sudo juice install --restart

Installing packages and extensions system-wide#

By default each service and the user container use the default environment. To add a package to this environment for everyone, configure orchestration.toml::environments.default.dependencies in the configuration file stored at /etc/juice/config/orchestration.toml. If the list already exists, add your package to the existing list to not override the other packages. For example, to add the package <package_name> or extension <extension_name>, add the following to the configuration file:

[environments.default]
dependencies = [
    # Existing packages
    "lab",
    # Add your packages and/or extensions here
    "<package_name>",
    "<extension_name>",
]

After adding the new packages or extensions, run the following command from the host system terminal to apply the changes. This will rebuild all environments and restart all services. Depending on the speed of your hard drive and network connection, this process may take several minutes.

sudo juice install --rebuild --restart

To add a package for yourself only, without administrator access, see Adding dependencies instead.