Development environment#

This guide explains how to set up a development environment for OrangeQS Juice. We provide two different ways to set up a development environment:

  • Using a development container. Runs the development environment in an isolated container and is supported on all operating systems.

  • Manual setup. Set up an environment manually on your machine, which requires a compatible Linux distribution.

Note

This guide is for setting up a development environment for contributing to the OrangeQS Juice core repository. If you want to set up a development environment for developing an extension, see Setting up a development environment for an extension.

Using a development container#

We provide a dev container configuration to easily start developing on OrangeQS Juice. We recommend using VS Code to work with the dev container, but you can also use other tools that support the dev container specification. The instructions below assume VS Code.

  1. Follow the dev container installation instructions for VS Code.

  2. Clone the repository:

    git clone [email protected]:orangeqs/juice.git

  3. Open the folder of the Juice repository in the dev container using the Dev Containers: Open folder in Container command in the Command Palette. You should not be prompted to select a container, it should use the provided configuration at .devcontainer/devcontainer.json by default.

  4. Wait until the container is built and the development dependencies are installed.

  5. Run juice --version in your terminal to confirm that everything works.

  6. (Optional) Run pytest to run the tests.

  7. (Optional) By default the dev container only installs the orangeqs-juice-core Python package and its development dependencies. If you want to install and start a full OrangeQS Juice deployment (including JupyterHub, database, services, etc.) you can run:

    sudo juice install

    This will use your local editable version of the Python package in all containers. Once the full Juice deployment is completed, you can then access the Jupyterhub at http://localhost:8888 with the default username orangeqs and password OrangeQS

Note

To develop on Windows, Juice needs to run inside WSL2. Performance on Windows using WSL2 is significantly worse than on native Linux. Therefore we strongly recommend using Linux to develop on OrangeQS Juice.

  1. Follow the dev container installation instructions for VS Code.

  2. Install WSL2 and a Linux distribution from the Microsoft Store (e.g. Ubuntu).

  3. Open a terminal in any WSL2 distribution and clone the repository.

    git clone https://gitlab.com/orangeqs/juice.git

    Warning

    Make sure to clone the repository in a WSL location, not on your Windows filesystem! Using your Windows filesystem will not work.

  4. Open the folder of the Juice repository in the dev container using the Dev Containers: Open folder in Container command in the Command Palette. You should not be prompted to select a container, it should use the provided configuration at .devcontainer/devcontainer.json by default.

  5. Wait until the container is built and the development dependencies are installed.

  6. Run juice --version in your terminal to confirm that everything works.

  7. (Optional) Run pytest to run the tests.

  8. (Optional) By default the dev container only installs the orangeqs-juice-core Python package and its development dependencies. If you want to install and start a full OrangeQS Juice deployment (including JupyterHub, database, services, etc.) you can run:

    sudo juice install

    This will use your local editable version of the Python package in all containers. Once the full Juice deployment is completed, you can then access the Jupyterhub at http://localhost:8888 with the default username orangeqs and password OrangeQS

Using a development container on macOS is not supported.

Tip

If you encounter any issues with your dev container, remember that you can always rebuild your container to get back to a clean state. To do this in VS Code, use the Dev Containers: Rebuild Container command in the Command Palette.

Manual setup#

If you do not use VS Code or wish to set up a development environment manually for other reasons you can follow the instructions below.

  1. Clone the repository:

    git clone [email protected]:orangeqs/juice.git

  2. Install the package in a virtual environment. We recommend using uv for managing your virtual environment. The next steps will assume that you are using uv.

    uv sync --extra dev

  3. Install pre-commit hooks.

    uv run pre-commit install

  4. Run the CLI to verify the installation.

    uv run juice --version

    Verify that the reported installation location is your local repository.

  5. (Optional) Run the tests:

    uv run pytest

Warning

The instructions above make the juice CLI available directly on your system. If you run juice install, it will install a full OrangeQS Juice deployment on your system, which may interfere with other software and is not easily removed.

  • If this is not what you want, please refer to Using a development container for using an isolated dev container instead.

  • If this is what you want, check that your Linux machine fulfills the System Requirements before running juice install.

Manual setup on Windows is not supported.

Manual setup on macOS is not supported.