`orchestration.toml`: Orchestration Settings#

orchestration.toml#

Settings for the installation of OrangeQS Juice.

Warning

Note that this is the only configuration file which can only be loaded from /etc/juice/config! This configuration file can thus only be modified by the system administrator, and not from the lab repository or extensions.

environments#

Type: object.

Common environments used by services and JupyterHub.

environments.default#

Type: object.

Settings for a uv-based environment in Juice.

environments.default.home_path#

Type: string. Default: '/home/user'.

The mount path of the home directory in the container.

environments.default.shared_path#

Type: string. Default: '~/shared'.

The mount path of the shared data folder in the container.

environments.default.shared_lib_path#

Type: string. Default: '~/shared/lib'.

The mount path of the shared lib folder in the container.

environments.default.container#

Type: object.

Partial settings for a container.

environments.default.container.volumes#

Type: list[string].

List of volume mounts for the container.

environments.default.container.environment#

Type: dict[string, string].

Dictionary of environment variables for the container.

environments.default.container.port_forwarding#

Type: list[object].

List of port mappings for the container.

environments.default.container.port_forwarding[]#

Type: object.

Port Forwarding configuration for a container.

environments.default.container.port_forwarding[].host_port#

Type: integer | null.

Host Port

environments.default.container.port_forwarding[].container_port#

Type: integer | null.

Container Port

environments.default.container.devices#

Type: list[string].

List of device mappings for the container.

environments.default.container.group_add#

Type: list[string].

List of additional groups to add the container user to.

environments.default.container.memory#

Type: string | null.

Memory limit for the container.

Expects a number suffixed by a unit (“K”, “M”, “G”, “T”), e.g., “512M” or “2G”. Note that the unit must be uppercase!

This option will be ignored for environment builds.

environments.default.base_image#

Type: string. Default: 'quay.io/almalinuxorg/almalinux:10'.

Base Image

environments.default.type#

Type: string. Default: 'uv'.

Type

environments.default.arch#

Type: string | null.

Arch

environments.default.python_version#

Type: string. Default: '3.12'.

Python Version

environments.default.dependencies#

Type: list[string].

Dependencies

environments.default.sources#

Type: dict[string, dict[string, string | boolean] | list[dict[string, string | boolean]]].

Sources

environments.default.pyproject_toml_extra#

Type: dict[string, any] | string.

Extra configuration for the generated pyproject.toml file of the environment.

Accepts both raw TOML as a multiline string or a dictionary representing parsed TOML that is merged into the generated pyproject.toml file.

This can be used to add extra fields to the pyproject.toml file, such as [tool.uv.index] entries to configure additional package indexes.

environments.default.system_packages#

Type: list[string].

List of system packages to install in the environment container.

These packages will be installed using dnf install.

environments.default.extra_dockerfile_lines#

Type: list[string].

List of extra lines to add to the generated Dockerfile for this environment.

These lines will be added exactly as provided into the Dockerfile. This means that for example commands should be prepended with RUN, e.g. RUN mkdir -p /some/directory. These lines are executed in the context of the root user before the Python packages of the environment are installed, after the base image is set and the system packages are installed.

data_folder#

Type: object.

Settings for data folder locations on the host system.

data_folder.env_data#

Type: string. Default: '/var/lib/juice/env'.

Folder with environment definitions created from the settings.

data_folder.service_data#

Type: string. Default: '/var/lib/juice/service'.

Service specific data files.

data_folder.dist_data#

Type: string. Default: '/var/lib/juice/dist'.

Folder containing wheels for Python packages.

data_folder.lib_data#

Type: string. Default: '/var/lib/juice/lib'.

Folder containing source code for Python packages for editable installs.

data_folder.user_data#

Type: string. Default: '/var/lib/juice/user'.

Folder containing the home directories of all users.

The home directories are stored in ./{username} subfolders.

data_folder.user_data_shared#

Type: string. Default: '/var/lib/juice/user/shared'.

Folder containing shared data for all users.

This is mounted as ~/shared in the container by default.

data_folder.shared_runtime_data#

Type: string. Default: '/var/run/juice'.

Shared runtime data folder.

This is where shared runtime data is stored, such as service info and kernel specs. Even though this folder contains service-specific secrets, for now this folder is shared with all users and OrangeQS Juice services.

This is mounted as /var/run/juice in the container by default.

data_folder.user_id#

Type: integer. Default: 1000.

The user ID to set as the owner of user data folders.

This should correspond to the juice-data user on the host system. This setting is set automatically on installation.

data_folder.group_id#

Type: integer. Default: 1000.

The group ID to set as the owner of user data folders.

This should correspond to the juice-data group on the host system. This setting is set automatically on installation.

services#

Type: dict[string, object].

Collection of OrangeQS Juice services to run.

The key corresponds to the name of the service.

services.{key}#

Type: object.

Settings for a OrangeQS Juice service.

services.{key}.environment#

Type: object.

Settings for a uv-based environment in Juice.

services.{key}.environment.home_path#

Type: string. Default: '/home/user'.

The mount path of the home directory in the container.

services.{key}.environment.shared_path#

Type: string. Default: '~/shared'.

The mount path of the shared data folder in the container.

services.{key}.environment.shared_lib_path#

Type: string. Default: '~/shared/lib'.

The mount path of the shared lib folder in the container.

services.{key}.environment.container#

Type: object.

Partial settings for a container.

services.{key}.environment.container.volumes#

Type: list[string].

List of volume mounts for the container.

services.{key}.environment.container.environment#

Type: dict[string, string].

Dictionary of environment variables for the container.

services.{key}.environment.container.port_forwarding#

Type: list[object].

List of port mappings for the container.

services.{key}.environment.container.port_forwarding[]#

Type: object.

Port Forwarding configuration for a container.

services.{key}.environment.container.port_forwarding[].host_port#

Type: integer | null.

Host Port

services.{key}.environment.container.port_forwarding[].container_port#

Type: integer | null.

Container Port

services.{key}.environment.container.devices#

Type: list[string].

List of device mappings for the container.

services.{key}.environment.container.group_add#

Type: list[string].

List of additional groups to add the container user to.

services.{key}.environment.container.memory#

Type: string | null.

Memory limit for the container.

Expects a number suffixed by a unit (“K”, “M”, “G”, “T”), e.g., “512M” or “2G”. Note that the unit must be uppercase!

This option will be ignored for environment builds.

services.{key}.environment.base_image#

Type: string. Default: 'quay.io/almalinuxorg/almalinux:10'.

Base Image

services.{key}.environment.type#

Type: string. Default: 'uv'.

Type

services.{key}.environment.arch#

Type: string | null.

Arch

services.{key}.environment.python_version#

Type: string. Default: '3.12'.

Python Version

services.{key}.environment.dependencies#

Type: list[string].

Dependencies

services.{key}.environment.sources#

Type: dict[string, dict[string, string | boolean] | list[dict[string, string | boolean]]].

Sources

services.{key}.environment.pyproject_toml_extra#

Type: dict[string, any] | string.

Extra configuration for the generated pyproject.toml file of the environment.

Accepts both raw TOML as a multiline string or a dictionary representing parsed TOML that is merged into the generated pyproject.toml file.

This can be used to add extra fields to the pyproject.toml file, such as [tool.uv.index] entries to configure additional package indexes.

services.{key}.environment.system_packages#

Type: list[string].

List of system packages to install in the environment container.

These packages will be installed using dnf install.

services.{key}.environment.extra_dockerfile_lines#

Type: list[string].

List of extra lines to add to the generated Dockerfile for this environment.

These lines will be added exactly as provided into the Dockerfile. This means that for example commands should be prepended with RUN, e.g. RUN mkdir -p /some/directory. These lines are executed in the context of the root user before the Python packages of the environment are installed, after the base image is set and the system packages are installed.

services.{key}.entrypoint#

Type: string. Default: 'orangeqs.juice.service:IPythonService'.

Class to use as the entrypoint for the service.

Uses the format <module>:<class>.

services.{key}.init_args#

Type: list[any].

List of arguments to pass to the service class on initialization.

Will be passed as *init_args to the service class.

services.{key}.init_kwargs#

Type: dict[string, any].

Dictionary of keyword arguments to pass to the service class on initialization.

Will be passed as **init_kwargs to the service class.

containerization#

Type: object.

Settings for containerization.

containerization.network_name#

Type: string. Default: 'juice'.

Network Name

containerization.container_type#

Type: string. Default: 'podman'.

Container Type

containerization.container_prefix#

Type: string. Default: 'juice-'.

Container Prefix

containerization.build_prefix#

Type: string. Default: 'juice-'.

Build Prefix

containerization.podman#

Type: object.

Settings for Podman containerization.

containerization.podman.container_folder#

Type: string. Default: '/etc/containers/systemd'.

Container Folder

influxdb2#

Type: object.

Settings for an instance of influxDB2.

influxdb2.url#

Type: string. Default: 'http://juice-influxdb2:8086'.

Url

influxdb2.org#

Type: string. Default: 'orangeqs-juice'.

Org

influxdb2.secrets_path#

Type: string. Default: '/etc/juice/influxdb2/secrets.env'.

Secrets Path

influxdb2.config_path#

Type: string. Default: '/etc/juice/influxdb2'.

Config Path

influxdb2.data_path#

Type: string. Default: '/var/lib/juice/influxdb2'.

Data Path

influxdb2.buckets#

Type: dict[string, object].

Buckets

influxdb2.buckets.{key}#

Type: object.

Settings for a single bucket of InfluxDB2 Instance.

influxdb2.buckets.{key}.name#

Type: string.

Name

influxdb2.buckets.{key}.retention#

Type: string. Default: '0s'.

The retention duration for the bucket.

See https://docs.influxdata.com/influxdb/v2/reference/cli/influx/bucket/update/#retention-periods for the format. A retention of “0s” means to retain data indefinitely.

influxdb2.buckets.{key}.description#

Type: string | null.

Description

influxdb2.buckets.{key}.org#

Type: string. Default: 'orangeqs-juice'.

Org

influxdb2.container#

Type: object.

Settings for spawning a container.

influxdb2.container.image#

Type: string.

Image

influxdb2.container.tag#

Type: string | null.

Tag

influxdb2.container.name#

Type: string.

Name

influxdb2.container.command#

Type: string | null.

Command

influxdb2.container.entrypoint#

Type: string | null.

Entrypoint

influxdb2.container.user#

Type: string | null.

User

influxdb2.container.workdir#

Type: string | null.

Workdir

influxdb2.container.volumes#

Type: list[string].

Volumes

influxdb2.container.environment#

Type: dict[string, string].

Environment

influxdb2.container.memory#

Type: string | null.

Memory

influxdb2.container.devices#

Type: list[string].

Devices

influxdb2.container.network#

Type: string. Default: 'juice'.

Network

influxdb2.container.privileged#

Type: boolean. Default: False.

Privileged

influxdb2.container.env_file#

Type: string | null.

Env File

influxdb2.container.port_forwarding#

Type: list[object].

Port Forwarding

influxdb2.container.port_forwarding[]#

Type: object.

Port Forwarding configuration for a container.

influxdb2.container.port_forwarding[].host_port#

Type: integer | null.

Host Port

influxdb2.container.port_forwarding[].container_port#

Type: integer | null.

Container Port

influxdb2.container.group_add#

Type: list[string].

Group Add

influxdb2.container.arch#

Type: string | null.

Arch

influxdb2.container.systemd#

Type: object.

Settings for the systemd service of a container.

influxdb2.container.systemd.unit#

Type: object.

Settings for the [Unit] section of the systemd service of a container.

Each field corresponds to an option in the [Unit] section of a systemd service. See https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html#%5BUnit%5D%20Section%20Options for more info.

influxdb2.container.systemd.unit.after#

Type: list[string].

After

influxdb2.container.systemd.unit.requires#

Type: list[string].

Requires

influxdb2.container.systemd.unit.wants#

Type: list[string].

Wants

influxdb2.container.systemd.service#

Type: object.

Settings for the [Service] section of the systemd service of a container.

Each field corresponds to an option in the [Service] section of a systemd service. See https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html#Options for more info.

influxdb2.container.systemd.service.restart#

Type: any.

Restart

influxdb2.container.systemd.service.restart_steps#

Type: integer | null.

Restart Steps

influxdb2.container.systemd.service.restart_sec#

Type: integer | null.

Restart Sec

influxdb2.container.systemd.service.timeout_start_sec#

Type: integer | null.

Timeout Start Sec

influxdb2.container.systemd.service.restart_max_delay_sec#

Type: integer | null.

Restart Max Delay Sec

influxdb2.container.systemd.service.exec_start_pre#

Type: list[string].

Exec Start Pre

influxdb2.container.systemd.service.exec_start_post#

Type: list[string].

Exec Start Post

influxdb2.container.systemd.service.exec_stop_post#

Type: list[string].

Exec Stop Post

jupyterhub#

Type: object.

Top-level settings for a JupyterHub instance managed by Juice.

jupyterhub.database_dir#

Type: string. Default: '/var/lib/juice/jupyterhub/database'.

Database Dir

jupyterhub.user_data_dir#

Type: string. Default: '/var/lib/juice/user'.

User Data Dir

jupyterhub.config_dir#

Type: string. Default: '/etc/juice/jupyterhub'.

Config Dir

jupyterhub.supervisor_config_dir#

Type: string. Default: '/etc/juice/jupyterhub/supervisor'.

Supervisor Config Dir

jupyterhub.main_hub#

Type: object.

Settings for the main Hub of a JupyterHub instance.

jupyterhub.main_hub.secrets_file#

Type: string. Default: 'secrets.env'.

File containing secrets for the JupyterHub instance.

jupyterhub.main_hub.config_file#

Type: string. Default: 'jupyterhub_config.py'.

File containing the JupyterHub configuration, rendered by Juice orchestration.

jupyterhub.main_hub.singleuser_config_file#

Type: string. Default: 'jupyter_singleuser_config.py'.

File containing the Jupyter Server configuration for singleuser containers.

jupyterhub.main_hub.authenticator_class#

Type: string. Default: 'pam'.

The authenticator class to use for JupyterHub.

Depending on the the authenticator class, the following contents are expected in the secrets_file. By default this file is at /etc/juice/jupyterhub/secrets.env.

'shared-password':

JUICE_JUPYTERHUB_SHARED_PASSWORD=<password for all users>
JUICE_JUPYTERHUB_ADMIN_PASSWORD=<admin password>

'pam': No additional secrets required.

'gitlab':

JUPYTERHUB_OAUTH_APP_ID=<OAuth application ID>
JUPYTERHUB_OAUTH_APP_SECRET=<OAuth application secret>
# Should not have a trailing slash, e.g. https://gitlab.com
JUPYTERHUB_OAUTH_GITLAB_URL=<GitLab instance URL>
# ID of the group whose members are allowed to log in, e.g. `54`.
JUPYTERHUB_OAUTH_GITLAB_GROUP=<Allowed GitLab group>

jupyterhub.main_hub.user_max_idle_timeout#

Type: integer. Default: 1800.

The maximum idle time (in seconds) for singleuser servers before culled.

jupyterhub.main_hub.port#

Type: integer. Default: 8888.

The port to access the JupyterHub instance on.

jupyterhub.main_hub.admin_users#

Type: list[string]. Default: ['root'].

List of admin users for the JupyterHub instance.

jupyterhub.main_hub.extra_config#

Type: string | null.

Extra configuration to add to the JupyterHub config file.

Useful for adding custom configuration options not directly supported.

jupyterhub.main_hub.oauth_callback_url#

Type: string | null.

The OAuth callback URL for the JupyterHub instance.

jupyterhub.singleuser#

Type: object.

Settings for the single-user servers spawned by the Hub.

jupyterhub.singleuser.home_path#

Type: string. Default: '/home/user'.

The mount path of the home directory in the container.

jupyterhub.singleuser.shared_path#

Type: string. Default: '~/shared'.

The mount path of the shared data folder in the container.

jupyterhub.singleuser.shared_lib_path#

Type: string. Default: '~/shared/lib'.

The mount path of the shared lib folder in the container.

jupyterhub.singleuser.environment#

Type: object.

Settings for a uv-based environment in Juice.

jupyterhub.singleuser.environment.home_path#

Type: string. Default: '/home/user'.

The mount path of the home directory in the container.

jupyterhub.singleuser.environment.shared_path#

Type: string. Default: '~/shared'.

The mount path of the shared data folder in the container.

jupyterhub.singleuser.environment.shared_lib_path#

Type: string. Default: '~/shared/lib'.

The mount path of the shared lib folder in the container.

jupyterhub.singleuser.environment.container#

Type: object.

Partial settings for a container.

jupyterhub.singleuser.environment.container.volumes#

Type: list[string].

List of volume mounts for the container.

jupyterhub.singleuser.environment.container.environment#

Type: dict[string, string].

Dictionary of environment variables for the container.

jupyterhub.singleuser.environment.container.port_forwarding#

Type: list[object].

List of port mappings for the container.

jupyterhub.singleuser.environment.container.port_forwarding[]#

Type: object.

Port Forwarding configuration for a container.

jupyterhub.singleuser.environment.container.port_forwarding[].host_port#

Type: integer | null.

Host Port

jupyterhub.singleuser.environment.container.port_forwarding[].container_port#

Type: integer | null.

Container Port

jupyterhub.singleuser.environment.container.devices#

Type: list[string].

List of device mappings for the container.

jupyterhub.singleuser.environment.container.group_add#

Type: list[string].

List of additional groups to add the container user to.

jupyterhub.singleuser.environment.container.memory#

Type: string | null.

Memory limit for the container.

Expects a number suffixed by a unit (“K”, “M”, “G”, “T”), e.g., “512M” or “2G”. Note that the unit must be uppercase!

This option will be ignored for environment builds.

jupyterhub.singleuser.environment.base_image#

Type: string. Default: 'quay.io/almalinuxorg/almalinux:10'.

Base Image

jupyterhub.singleuser.environment.type#

Type: string. Default: 'uv'.

Type

jupyterhub.singleuser.environment.arch#

Type: string | null.

Arch

jupyterhub.singleuser.environment.python_version#

Type: string. Default: '3.12'.

Python Version

jupyterhub.singleuser.environment.dependencies#

Type: list[string].

Dependencies

jupyterhub.singleuser.environment.sources#

Type: dict[string, dict[string, string | boolean] | list[dict[string, string | boolean]]].

Sources

jupyterhub.singleuser.environment.pyproject_toml_extra#

Type: dict[string, any] | string.

Extra configuration for the generated pyproject.toml file of the environment.

Accepts both raw TOML as a multiline string or a dictionary representing parsed TOML that is merged into the generated pyproject.toml file.

This can be used to add extra fields to the pyproject.toml file, such as [tool.uv.index] entries to configure additional package indexes.

jupyterhub.singleuser.environment.system_packages#

Type: list[string].

List of system packages to install in the environment container.

These packages will be installed using dnf install.

jupyterhub.singleuser.environment.extra_dockerfile_lines#

Type: list[string].

List of extra lines to add to the generated Dockerfile for this environment.

These lines will be added exactly as provided into the Dockerfile. This means that for example commands should be prepended with RUN, e.g. RUN mkdir -p /some/directory. These lines are executed in the context of the root user before the Python packages of the environment are installed, after the base image is set and the system packages are installed.

jupyterhub.singleuser.dashboard_log_file#

Type: string. Default: '/tmp/user/dashboard_log'.

The file where dashboard logs are stored.

jupyterhub.singleuser.extra_config#

Type: string | null.

Extra configuration to add to the JupyterHub singleuser config file.

Useful for adding custom configuration options not directly supported.

jupyterhub.singleuser.cmd#

Type: list[string]. Default: ['/env/.venv/bin/supervisord', '-c', '/env/supervisor/supervisord.conf'].

The command to run in the singleuser server container.

orchestration.toml: Orchestration Settings#

`orchestration.toml`: Orchestration Settings#