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

Type: list[string].

List of system packages to install in the environment container.

These packages will be installed using dnf install.

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.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}.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.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.dashboard_log_file

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

The file where dashboard logs are stored.

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.