First steps after installation#

After installing OrangeQS Juice, a basic configuration is applied to get you started quickly. This guide will help you take the first steps to access and use the Juice interface and apply some common configurations.

Required privileges

Unless explicitly stated otherwise, the actions in this guide should be performed in the host system terminal by an administrator with sudo privileges.

Accessing the Juice interface#

From the computer where you installed Juice, navigate to http://localhost:8888 in the web browser to access the web interface.

Accessing from other computers (optional). An easy way to access the Juice interface from other computers on your network is to set up an SSH tunnel. This requires SSH access to the computer where Juice is installed. If you normally login remotely over SSH using ssh <user>@<host>, you can create the tunnel with the following command from your remote computer:

ssh -L 8888:localhost:8888 <user>@<host>

This will forward your local port 8888 to the remote host’s port 8888. Now you can navigate to http://localhost:8888 on your local machine to access the Juice interface running on the remote host.

Setting up a HTTPS reverse proxy (optional). If you want to permanently and publicly access your Juice interface, it is recommended to set up a HTTPS reverse proxy. There are different ways to do this, below we have listed a few options:

Caddy. Simple web server with automatic HTTPS support. Requires a public IP address.
Cloudflare Tunnel. Useful if you are in a constrained network and do not have a public IP address.

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 Juice extensions and Python packages#

OrangeQS Juice extensions are Python packages that add extra functionality to the Juice environment. There are two ways to install Juice extensions or Python packages.

From the system configuration orchestration.toml. By default each service and the user container use the default environment. To add a package to this environment, 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>",
]
```
From the lab repository. By default, each environment has the lab repository installed. The lab repository is an editable Python package, accessible from JupyterLab at ~/shared/lib/lab. By adding packages or extensions as dependencies to the lab repository, they will be installed in the environment. This can be done by adding them to the project.dependencies list of ~/shared/lib/lab/pyproject.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:
```
[project]
# ... other contents ...
dependencies = [
    # Existing packages
    "orangeqs-juice-core",
    # Add your packages and/or extensions here
    "<package_name>",
    "<extension_name>",
]
# ... other contents ...
```

After adding the new packages or extensions using either method, 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