Installation#

This section explains how to install a production environment of OrangeQS Juice.

Development environment

This guide covers deploying OrangeQS Juice to a production environment.

For instructions on setting up a development environment, see the Development Environment section.

System Requirements#

Software Requirements#

OrangeQS Juice is released as .deb and .rpm packages and can run on any Linux distribution that matches the following requirements. The explicitly tested and supported distributions are AlmaLinux 10 and Ubuntu 26.

  • Linux operating system managed by systemd.

  • Root access.

  • The systemctl command available.

  • Podman version >=5.x installed.

  • Either telegraf and rsyslog are installed, or your system uses the dnf or apt package manager

Hardware Requirements#

  • While not a strict requirement, we also strongly recommend using an SSD for your OS partition for a good experience.

Initial Setup#

  1. Ensure you are running AlmaLinux 10 or Ubuntu 26 and logged in as root.

Run the following setup steps for your distribution:

  1. Due to an issue with environment handling, SELinux must be set to permissive mode before installing OrangeQS Juice.

  2. Install jq.

    dnf install jq

  3. Install the script to download the latest version of OrangeQS Juice:

    curl --fail "https://gitlab.com/orangeqs/juice/-/raw/main/packaging/download-latest-proxy.sh" > /bin/juice-download-latest && chmod +x /bin/juice-download-latest

  4. The script is available at /bin/juice-download-latest. Verify its contents using:

    cat /bin/juice-download-latest

  1. Ensure you are logged in as root.

  2. Install curl.

    apt update && apt install curl

  3. Install the script to download the latest version of OrangeQS Juice:

    curl --fail "https://gitlab.com/orangeqs/juice/-/raw/main/packaging/download-latest-proxy.sh" > /bin/juice-download-latest && chmod +x /bin/juice-download-latest

  4. The script is available at /bin/juice-download-latest. Verify its contents using:

    cat /bin/juice-download-latest

Installation#

To install OrangeQS Juice, follow these steps:

  1. Ensure you are logged in as root.

  2. Install the latest version of the OrangeQS Juice system package:

    dnf install $(juice-download-latest)

    To install a specific version of Juice, run

    dnf install $(juice-download-latest stable <version>)

    For example

    dnf install $(juice-download-latest stable v26.13.0)

    This would install v26.13.0. If unspecified, the latest version is pulled.

    Ensure first running apt update to update the package index, then run

    apt update && apt install $(juice-download-latest)

    To install a specific version, run

    apt update && apt install $(juice-download-latest stable <version>)

    For example

    apt update && apt install $(juice-download-latest stable v26.13.0)

    This would install v26.13.0. If unspecified, the latest version is pulled.

  3. Install system services and configurations: Depending on the speed of your hard drive and network, this might take up to 30 minutes as it has to build multiple container images.

    juice install

    Consent for Basic Metrics Collection

    When you install Juice, you will be asked to consent to the collection of a small set of anonymous usage metrics. These metrics are collected via the open‑source package orangeqs-zest.

    We use this data solely to understand the number of active users and the frequency of updates, helping us prioritize maintenance and guide future development. No experimental or sensitive information is collected. You will always be able to use all functionality without consenting to the collection of data.

    For more details, see Telemetry Policy.

    Improving installation time on hard-drives

    The Juice installation has to build several Docker images. For installing Juice on a hard-drive, it’s recommended to use the --no-parallel-build option to build these images sequentially. This is usually faster, as it reduces the amount of random access on the hard-drive.

    juice install --no-parallel-build

    This option is not recommended for SSDs.

  4. You can now access the JupyterHub interface at http://localhost:8888. You can login with any user configured on the host unix system.

Updating#

Updating OrangeQS Juice is similar to the installation process.

  1. Ensure you are logged in as root.

  2. Install the latest beta version of the OrangeQS Juice system package:

    dnf install $(juice-download-latest)

    Ensure first running apt update to update the package index, then run

    apt install $(juice-download-latest)

  3. Update configurations, rebuild, and restart all services Be advised that this will restart all components of OrangeQS Juice. Depending on the speed of your hard drive and network, this might take up to 30 minutes as it has to build multiple container images.

    juice install --rebuild --restart

    Improving update time on hard-drives

    The Juice update has to build several Docker images. If you have installed Juice on a hard-drive, it’s recommended to use the --no-parallel-build option to build these images sequentially. This is usually faster, as it reduces the amount of random access on the hard-drive.

    juice install --rebuild --restart --no-parallel-build

    This option is not recommended for SSDs.

What’s next?#

Continue to First steps after installation for more information on accessing the Juice interface and performing common configurations.