Development environment#

This guide explains how to set up a development environment for your OrangeQS Juice extension.

Not implemented yet!

This section is part of documentation-driven development, thus its contents are not yet functional and open for feedback!

Setting up a development container#

We will set up the development environment in a development container, which runs the development environment in an isolated container and is supported on all operating systems. If you are using VS Code or any other IDE that supports dev containers you can let your development environment be set up automatically from a configuration file.

Start by creating a Dockerfile and a devcontainer.json configuration file for the dev container.

Click to see file contents

.devcontainer/devcontainer.json

{
    "build": {
        "dockerfile": "Dockerfile",
        "context": "."
    },
    "privileged": true,
    "overrideCommand": false,
    "capAdd": [
        "SYS_ADMIN",
        "SYS_PTRACE"
    ],
    "forwardPorts": [8086, 8000],
    "workspaceFolder": "/var/lib/juice/dist/$project",
    "mounts": [
        "source=/var/lib/containers,target=/var/lib/containers,type=bind"
    ],
    "runArgs": ["--name", "juice-extension-devcontainer"],
    "customizations": {
        "vscode": {
            "settings": {
                "cSpell.language": "en,en-US"
            },
            "extensions": [
                "ms-python.vscode-pylance",
                "ms-python.python",
                "ms-python.debugpy",
                "charliermarsh.ruff",
                "eamodio.gitlens",
                "tamasfe.even-better-toml"
            ]
        }
    },
    "postAttachCommand": "pip install -e ."
}

.devcontainer/Dockerfile

FROM quay.io/almalinuxorg/10-init
ENV LANG=C.UTF-8 LC_ALL=C.UTF-8

# Configure to use iptables for containers instead of nftables
# Required for podman to work on WSL systems
RUN mkdir -p /etc/containers
RUN echo -e "[network]\nfirewall_driver = \"iptables\"" > /etc/containers/containers.conf

RUN /usr/bin/dnf install -y \
    git \
    rpm-build \
    ruby \
    sudo \
    podman \
    python3 \
    python3-pip \
    iputils \
    nano \
    iptables \
    && /usr/bin/dnf clean all

RUN /usr/bin/gem install fpm

ARG USERNAME=user
ARG USER_UID=1000
ARG USER_GID=$USER_UID

# Add a non-root user with passwordless sudo access
# This is user is not used by default, but can be used for development purposes.
RUN groupadd --gid $USER_GID $USERNAME \
    && useradd --uid $USER_UID --gid $USER_GID -m $USERNAME \
    && echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/$USERNAME \
    && chmod 0440 /etc/sudoers.d/$USERNAME

The folder structure of your extension should now look like this:

juice_extension_example
├── .devcontainer
│   ├── devcontainer.json
│   └── Dockerfile
└── other project files

Next, start the dev container. If you are using VS Code you can follow these instructions.

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

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

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

  4. Run juice --version in your terminal to confirm that the Juice orchestrator is correctly installed.

  5. Run pip list | grep juice_extension_example to confirm your extension is installed in editable mode.

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.

Starting OrangeQS Juice#

Next we should start OrangeQS Juice such that we can access the installation from a JupyterHub user container. To set up and start a full OrangeQS Juice deployment (including JupyterHub, database, services, etc.) you can run juice install. Since your extension has been installed in editable mode in the same environment as the Juice orchestrator, your extension will be automatically installed in the environments used by the user containers and services. Installing from editable mode is only meant for development, in production you should add your extension to the environment configuration.

After juice install has finished, you can open http://localhost:8000 in your browser to access the JupyterHub interface. The password can be found using cat /etc/juice/jupyterhub/secrets.env in your dev container. Check whether your extension is installed correctly in your user container by opening a new notebook and executing import juice_extension_example.

If you make modifications to your extension, you should consider which parts of OrangeQS Juice need to be restarted to reflect your changes. Below is a guideline which lists some common cases:

  • Changing a Python file which is used in

    • a service: Restart the service by running systemctl restart juice-{service} in the dev container.

    • your notebook: Restart your notebook kernel.

  • Changing a dependency: Rebuild the environment by running juice install --rebuild --restart in the dev container.

Next, let’s continue by adding some functionality to the extension.