`orangeqs.juice.orchestration.settings`#

Configuration fort the OrangeQS Juice orchestrator.

Module Contents#

Classes#

`DataFolderSettings`	Settings for data folder locations on the host system.
`ContainerFolderSettings`	Settings for the target mount locations of standard folders.
`PodmanSettings`	Settings for Podman containerization.
`ContainerizationSettings`	Settings for containerization.
`PortMapping`	Port Forwarding configuration for a container.
`SystemdUnitSettings`	Settings for the [Unit] section of the systemd service of a container.
`SystemdServiceSettings`	Settings for the [Service] section of the systemd service of a container.
`SystemdSettings`	Settings for the systemd service of a container.
`ContainerSettings`	Settings for spawning a container.
`BuildSettings`	Settings for building a container image.
`InfluxDB2BucketDescription`	Settings for a single bucket of InfluxDB2 Instance.
`InfluxDB2InstanceSettings`	Settings for an instance of influxDB2.
`TelegrafSettings`	Settings for configuring Telegraf outputs.
`PartialContainerSettings`	Partial settings for a container.
`BaseEnvironmentSettings`	Base class for environment settings.
`UvEnvironmentSettings`	Settings for a `uv`-based environment in Juice.
`EnvironmentsSettings`	Common environments used by services and JupyterHub.
`JupyterHubMainHubSettings`	Settings for the main Hub of a JupyterHub instance.
`JupyterHubSingleUserServerSettings`	Settings for the single-user servers spawned by the Hub.
`JupyterHubInstanceSettings`	Top-level settings for a JupyterHub instance managed by Juice.
`ServiceSettings`	Settings for a OrangeQS Juice service.
`OrchestrationSettings`	Settings for the installation of OrangeQS Juice.

Functions#

juice_install_source

Attempt to find an installation source of the Juice Python package.

Data#

`BUNDLED_WHEEL_PATH`	Path to the bundled wheel file of the OrangeQS Juice package as part of the system package. Note that this file does not necessarily exist, for example in development installations.
`UvSourcesType`
`EnvironmentSettings`	Union type for all types of environment settings supported by OrangeQS Juice.

API#

orangeqs.juice.orchestration.settings.BUNDLED_WHEEL_PATH#

None

Path to the bundled wheel file of the OrangeQS Juice package as part of the system package. Note that this file does not necessarily exist, for example in development installations.

class orangeqs.juice.orchestration.settings.DataFolderSettings(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

Settings for data folder locations on the host system.

model_config#: ‘ConfigDict(…)’

env_data: str#

‘/var/lib/juice/env’

Folder with environment definitions created from the settings.

service_data: str#

‘/var/lib/juice/service’

Service specific data files.

dist_data: str#

‘/var/lib/juice/dist’

Folder containing wheels for Python packages.

lib_data: str#

‘/var/lib/juice/lib’

Folder containing source code for Python packages for editable installs.

user_data: str#

‘/var/lib/juice/user’

Folder containing the home directories of all users.

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

user_data_shared: str#

‘/var/lib/juice/user/shared’

Folder containing shared data for all users.

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

shared_runtime_data: str#

‘/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.

user_id: int#

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.

group_id: int#

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.

class orangeqs.juice.orchestration.settings.ContainerFolderSettings(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

Settings for the target mount locations of standard folders.

home_path: str#

‘/home/user’

The mount path of the home directory in the container.

shared_path: str#

‘~/shared’

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

shared_lib_path: str#

‘~/shared/lib’

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

class orangeqs.juice.orchestration.settings.PodmanSettings(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

Settings for Podman containerization.

container_folder: str#: ‘/etc/containers/systemd’

class orangeqs.juice.orchestration.settings.ContainerizationSettings(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

Settings for containerization.

network_name: str#: ‘juice’

container_type: Literal[orangeqs.juice.orchestration.settings.ContainerizationSettings.podman]#: ‘podman’

container_prefix: str#: ‘juice-’

build_prefix: str#: ‘juice-’

podman: orangeqs.juice.orchestration.settings.PodmanSettings#: ‘Field(…)’

class orangeqs.juice.orchestration.settings.PortMapping(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

Port Forwarding configuration for a container.

host_port: int | None#: None

container_port: int | None#: None

class orangeqs.juice.orchestration.settings.SystemdUnitSettings(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

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.

after: list[str]#: ‘Field(…)’

requires: list[str]#: ‘Field(…)’

wants: list[str]#: ‘Field(…)’

class orangeqs.juice.orchestration.settings.SystemdServiceSettings(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

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.

restart: Literal[no, on-success, on-failure, on-abnormal, on-watchdog, on-abort, always, None]#: None

restart_steps: int | None#: None

restart_sec: int | None#: None

timeout_start_sec: int | None#: None

restart_max_delay_sec: int | None#: None

exec_start_pre: list[str]#: ‘Field(…)’

exec_start_post: list[str]#: ‘Field(…)’

exec_stop_post: list[str]#: ‘Field(…)’

class orangeqs.juice.orchestration.settings.SystemdSettings(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

Settings for the systemd service of a container.

unit: orangeqs.juice.orchestration.settings.SystemdUnitSettings#: ‘Field(…)’

service: orangeqs.juice.orchestration.settings.SystemdServiceSettings#: ‘Field(…)’

class orangeqs.juice.orchestration.settings.ContainerSettings(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

Settings for spawning a container.

image: str#: None

tag: str | None#: None

name: str#: None

command: str | None#: None

entrypoint: str | None#: None

user: str | None#: None

workdir: str | None#: None

volumes: list[str]#: ‘Field(…)’

environment: dict[str, str]#: ‘Field(…)’

memory: str | None#: None

devices: list[str]#: ‘Field(…)’

network: str#: ‘juice’

privileged: bool#: False

env_file: str | None#: None

port_forwarding: list[orangeqs.juice.orchestration.settings.PortMapping]#: ‘Field(…)’

group_add: list[str]#: ‘Field(…)’

arch: str | None#: None

systemd: orangeqs.juice.orchestration.settings.SystemdSettings#: ‘SystemdSettings(…)’

update(other: orangeqs.juice.orchestration.settings.PartialContainerSettings) → None#: Update this instance in-place with additional container setting.

class orangeqs.juice.orchestration.settings.BuildSettings(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

Settings for building a container image.

name: str#: None

file: str | None#: None

workdir: str | None#: None

volumes: list[str]#: ‘Field(…)’

environment: dict[str, str]#: ‘Field(…)’

arch: str | None#: None

build_args: dict[str, str]#: ‘Field(…)’

systemd: orangeqs.juice.orchestration.settings.SystemdSettings#: ‘Field(…)’

update(other: orangeqs.juice.orchestration.settings.PartialContainerSettings) → None#: Update this instance in-place with additional build settings.

class orangeqs.juice.orchestration.settings.InfluxDB2BucketDescription(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

Settings for a single bucket of InfluxDB2 Instance.

name: str#: None

retention: str#

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

description: str | None#: None

org: str#: ‘orangeqs-juice’

class orangeqs.juice.orchestration.settings.InfluxDB2InstanceSettings(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

Settings for an instance of influxDB2.

url: str#: ‘http://juice-influxdb2:8086’

org: str#: ‘orangeqs-juice’

secrets_path: str#: ‘/etc/juice/influxdb2/secrets.env’

config_path: str#: ‘/etc/juice/influxdb2’

data_path: str#: ‘/var/lib/juice/influxdb2’

buckets: dict[str, orangeqs.juice.orchestration.settings.InfluxDB2BucketDescription]#: ‘Field(…)’

container: orangeqs.juice.orchestration.settings.ContainerSettings#: ‘ContainerSettings(…)’

class orangeqs.juice.orchestration.settings.TelegrafSettings(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

Settings for configuring Telegraf outputs.

influxdb2_org: str#: None

influxdb2_bucket: str#: None

influxdb2_url: str#: None

config_path: str#: None

podman_stats_interval: str#: None

podman_stats_timeout: str#: None

class orangeqs.juice.orchestration.settings.PartialContainerSettings(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

Partial settings for a container.

volumes: list[str]#

‘Field(…)’

List of volume mounts for the container.

environment: dict[str, str]#

‘Field(…)’

Dictionary of environment variables for the container.

port_forwarding: list[orangeqs.juice.orchestration.settings.PortMapping]#

‘Field(…)’

List of port mappings for the container.

devices: list[str]#

‘Field(…)’

List of device mappings for the container.

group_add: list[str]#

‘Field(…)’

List of additional groups to add the container user to.

memory: str | None#

None

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.

class orangeqs.juice.orchestration.settings.BaseEnvironmentSettings(/, **data: Any)#

Bases: orangeqs.juice.orchestration.settings.ContainerFolderSettings

Base class for environment settings.

container: orangeqs.juice.orchestration.settings.PartialContainerSettings#

‘Field(…)’

Additional settings for the container of an environment.

These settings are merged on top of the default settings generated for the environment. These settings are applied both to the build container and the runtime container.

orangeqs.juice.orchestration.settings.UvSourcesType#: None

class orangeqs.juice.orchestration.settings.UvEnvironmentSettings(/, **data: Any)#

Bases: orangeqs.juice.orchestration.settings.BaseEnvironmentSettings

Settings for a uv-based environment in Juice.

base_image: str#: ‘quay.io/almalinuxorg/almalinux:10’

type: Literal[uv]#: ‘uv’

arch: str | None#: None

python_version: str#: ‘3.12’

dependencies: list[str]#: ‘Field(…)’

sources: orangeqs.juice.orchestration.settings.UvSourcesType#: ‘Field(…)’

pyproject_toml_extra: dict[str, Any] | str#

‘Field(…)’

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.

system_packages: list[str]#

‘Field(…)’

List of system packages to install in the environment container.

These packages will be installed using dnf install.

extra_dockerfile_lines: list[str]#

‘Field(…)’

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.

orangeqs.juice.orchestration.settings.EnvironmentSettings#

None

Union type for all types of environment settings supported by OrangeQS Juice.

Currently only supports UvEnvironmentSettings.

class orangeqs.juice.orchestration.settings.EnvironmentsSettings(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

Common environments used by services and JupyterHub.

default: orangeqs.juice.orchestration.settings.EnvironmentSettings#

‘Field(…)’

The default environment to use for services and JupyterHub.

This environment is used when a service or JupyterHub does not specify its own environment. To specify an environment for a specific service or JupyterHub, set the environment field in the respective settings. The format is the same as this field.

class orangeqs.juice.orchestration.settings.JupyterHubMainHubSettings(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

Settings for the main Hub of a JupyterHub instance.

secrets_file: str#

‘secrets.env’

File containing secrets for the JupyterHub instance.

config_file: str#

‘jupyterhub_config.py’

File containing the JupyterHub configuration, rendered by Juice orchestration.

singleuser_config_file: str#

‘jupyter_singleuser_config.py’

File containing the Jupyter Server configuration for singleuser containers.

authenticator_class: Literal[shared-password, pam, gitlab]#

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

user_max_idle_timeout: int#

1800

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

port: int#

8888

The port to access the JupyterHub instance on.

admin_users: list[str]#

[‘root’]

List of admin users for the JupyterHub instance.

extra_config: str | None#

None

Extra configuration to add to the JupyterHub config file.

Useful for adding custom configuration options not directly supported.

oauth_callback_url: str | None#

None

The OAuth callback URL for the JupyterHub instance.

class orangeqs.juice.orchestration.settings.JupyterHubSingleUserServerSettings(/, **data: Any)#

Bases: orangeqs.juice.orchestration.settings.ContainerFolderSettings

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

environment: orangeqs.juice.orchestration.settings.EnvironmentSettings#

None

The environment to use for singleuser servers.

Defaults to environments.default if not specified. When overriding the environment, be aware that it does not inherit from the default environment!

This environment will always have jupyterhub, jupyterlab and jupyter-server-proxy added as dependencies automatically.

dashboard_log_file: str#

‘/tmp/user/dashboard_log’

The file where dashboard logs are stored.

extra_config: str | None#

None

Extra configuration to add to the JupyterHub singleuser config file.

Useful for adding custom configuration options not directly supported.

cmd: list[str]#

[‘/env/.venv/bin/supervisord’, ‘-c’, ‘/env/supervisor/supervisord.conf’]

The command to run in the singleuser server container.

class orangeqs.juice.orchestration.settings.JupyterHubInstanceSettings(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

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

database_dir: str#: ‘/var/lib/juice/jupyterhub/database’

user_data_dir: str#: ‘/var/lib/juice/user’

config_dir: str#: ‘/etc/juice/jupyterhub’

supervisor_config_dir: str#: ‘/etc/juice/jupyterhub/supervisor’

main_hub: orangeqs.juice.orchestration.settings.JupyterHubMainHubSettings#: ‘Field(…)’

singleuser: orangeqs.juice.orchestration.settings.JupyterHubSingleUserServerSettings#: ‘Field(…)’

property build: orangeqs.juice.orchestration.settings.BuildSettings#: Generate build service settings.

property container: orangeqs.juice.orchestration.settings.ContainerSettings#: Generate Jupyterhub Container settings.

class orangeqs.juice.orchestration.settings.ServiceSettings(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

Settings for a OrangeQS Juice service.

environment: orangeqs.juice.orchestration.settings.EnvironmentSettings#

None

The environment definition to use for the service.

Defaults to environments.default if not specified. When overriding the environment, be aware that it does not inherit from the default environment!

entrypoint: str#

‘orangeqs.juice.service:IPythonService’

Class to use as the entrypoint for the service.

Uses the format <module>:<class>.

init_args: list[Any]#

‘Field(…)’

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

Will be passed as *init_args to the service class.

init_kwargs: dict[str, Any]#

‘Field(…)’

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

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

class orangeqs.juice.orchestration.settings.OrchestrationSettings(/, **data: Any)#

Bases: orangeqs.juice.settings.Configurable

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.

filename: ClassVar[str]#: ‘orchestration’

environments: orangeqs.juice.orchestration.settings.EnvironmentsSettings#

‘Field(…)’

Common environments used by services and JupyterHub.

data_folder: orangeqs.juice.orchestration.settings.DataFolderSettings#

‘Field(…)’

Settings for data folder locations on the host system.

services: dict[str, orangeqs.juice.orchestration.settings.ServiceSettings]#

‘Field(…)’

Collection of OrangeQS Juice services to run.

The key corresponds to the name of the service.

containerization: orangeqs.juice.orchestration.settings.ContainerizationSettings#: ‘Field(…)’

influxdb2: orangeqs.juice.orchestration.settings.InfluxDB2InstanceSettings#: ‘Field(…)’

jupyterhub: orangeqs.juice.orchestration.settings.JupyterHubInstanceSettings#

‘Field(…)’

Configuration for the JupyterHub instance managed by Juice.

property telegraf: orangeqs.juice.orchestration.settings.TelegrafSettings#: Generate Telegraf settings.

orangeqs.juice.orchestration.settings.juice_install_source() → tuple[Literal[editable, wheel, release], str] | None#

Attempt to find an installation source of the Juice Python package.

If the package is installed in editable mode, it will return the path to the source directory. Otherwise it will look for a wheel file in common locations (part of the system package). If running a released version, it will return the dependency specifier.

Returns#

(tuple or None): If a suitable source is found, returns tuple of the source type (“editable”, “wheel” or “release”) and the path to the source. If no suitable source is found, returns None.

orangeqs.juice.orchestration.settings#

Module Contents#

Classes#

Functions#

Data#

API#

Returns#

`orangeqs.juice.orchestration.settings`#