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#

Run the following setup steps for your distribution:

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

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

  3. Install jq.

    dnf install jq

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

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

    cat /bin/juice-download-latest

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

  2. Install jq.

    apt update && apt install jq

  3. Install curl.

    apt install curl

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

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

    cat /bin/juice-download-latest

Install Ubuntu 26 in WSL by running wsl --install -d Ubuntu-26.04 in PowerShell. All the requirements above then apply inside WSL.

Extra setup for WSL

Depending on your setup, you may need some extra configuration on the Windows side. This list covers common cases but isn’t exhaustive.

  • USB devices: WSL doesn’t see USB devices plugged into Windows. Forward them into WSL with usbipd-win, following Microsoft’s Connect USB devices guide.

  • Network access to lab hardware: by default, WSL sits behind a NAT on its own private subnet, so devices and other computers on your LAN may not be able to reach Juice. See Microsoft’s Accessing network applications with WSL guide for the options.

  • Keeping the PC awake: Juice stops whenever Windows sleeps, hibernates or restarts. In Settings > System > Power & battery, set the sleep and hibernate timeouts to Never, and set Windows Update’s active hours so it doesn’t restart the PC during measurements.

  • Keeping WSL running: WSL shuts down an idle distribution after 15 seconds, even if Juice’s services are still running inside it. Disable this with instanceIdleTimeout=-1 (see the .wslconfig below). WSL also doesn’t start on its own when Windows boots. To start it at log-on, create a Task Scheduler task that runs wsl.exe -d Ubuntu-26.04 --exec true.

  • Memory: WSL gives its VM 50% of the Windows RAM by default. If that isn’t enough for the services you run, raise it with the memory setting.

These settings go in %UserProfile%\.wslconfig on Windows. Run wsl --shutdown in PowerShell afterwards for them to take effect:

[wsl2]
memory=16GB

[general]
instanceIdleTimeout=-1

If you run into a case that isn’t listed here, please share it on the OrangeQS community forum so we can add it for everyone.

  1. Ensure you are running Ubuntu 26 inside WSL and logged in as root.

  2. Install jq.

    apt update && apt install jq

  3. Install curl.

    apt install curl

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

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

    cat /bin/juice-download-latest

  6. Before moving on to the Installation section below, apply the following, since the WSL2 kernel does not support the bridge nftables table family that Podman’s default firewall driver relies on:

    mkdir -p /etc/containers
cat <<'EOF' > /etc/containers/containers.conf
[network]
firewall_driver = "iptables"
EOF
apt install iptables

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.

    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 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)

    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 to access the Juice interface and make your own code available to it.