Container Configuration¶
Overview | Platform Architecture | Container Configuration | The Oasis REST API | Distributed Execution and Scaling | Configuration for Distribution and Scaling
There are two methods for setting configuration options on an oasis container. (1) by setting a shell environment variable on the container. (2) by adjusting a conf.ini file within the container.
Environment Variable Overrides¶
Configuration for OASIS Docker containers is primarily managed via a conf.ini file, which establishes default values. However, the preferred and highest-precedence method for dynamic configuration is through shell environment variables.
Naming Convention¶
To ensure an environment variable is recognized and applied, it must be prefixed with OASIS_. Any environment variable lacking this prefix will be ignored by the OASIS applications.
Example: Setting OASIS_DEBUG=True will override the default DEBUG=False value found in the conf.ini file.
conf.ini Location and Loading¶
The canonical conf.ini file is located at OasisLMF/OasisPlatform/conf.ini within the OasisPlatform repository. This file provides the base configuration, but its effective path and how it’s consumed differs based on the container type:
Model Worker Images:
Container Path: /home/worker/conf.ini
Integration: Values from this conf.ini are loaded and directly influence the configuration within Celery’s task processing files.
Server Images (Django):
Container Path: /var/www/oasis/conf.ini
Integration: Values from this conf.ini are loaded into Django’s settings.py configuration file, forming the application’s core settings.
Precedence Hierarchy¶
When an OASIS container starts, configuration values are applied in the following order of precedence, with later steps overriding earlier ones:
conf.ini Defaults: Values read from the conf.ini file ([default], [server], [worker], [celery] sections, respecting section-specific overrides).
OASIS_ Prefixed Environment Variables: Any environment variable set with the OASIS_ prefix (e.g., OASIS_DEBUG) will always override a corresponding setting derived from the conf.ini file.
This ensures that you can define sensible defaults within your image, while maintaining the flexibility to adjust specific parameters at deployment time using environment variables, without needing to rebuild or modify the container image itself.
Understanding conf.ini Structure and Precedence¶
The conf.ini file employs a standard INI file format, organized into sections, each containing key-value pairs. The sections define the scope of the configuration:
[default]: This section contains settings that apply universally to all container types (servers and workers).
[server]: Settings in this section are specific to server (e.g., Django) containers. Any key-value pair defined here will override a similarly named key in the [default] section when accessed by a server.
[worker]: Similar to [server], this section holds configurations unique to worker containers. Settings here will override [default] settings for workers.
[celery]: This section is dedicated to Celery-specific configuration options and applies to both server and worker container types, assuming both might interact with Celery.
Precedence Rules¶
Environment Variables (Highest Precedence): An environment variable OASIS_SETTING_NAME_TO_GET=<value> will always override any setting, regardless of the conf.ini file. This provides the most dynamic and immediate way to adjust configurations without modifying the file itself.
Specific Section Overrides Default: For server containers, values in [server] take precedence over [default]. For worker containers, values in [worker] take precedence over [default].
[celery] Section: Settings within [celery] are additive and specifically for Celery. They don’t directly override [default], [server], or [worker] in the same way, but rather provide a dedicated namespace for Celery configurations that both server and worker processes can utilize.
Server Container Configuration Options¶
These options are specifically applicable to the coreoasis/api_server containers and can be set via environment variables (prefixed with OASIS_, OASIS_{ini sections}_{variable}) or within the conf.ini file’s [server] or [default] sections.
For example OASIS_DB_PASS=<value> or OASIS_SERVER_DB_PASS=<value> will both work.
Django Core Options¶
Option Name |
Type |
Default |
Description |
---|---|---|---|
MEDIA_ROOT |
String |
(Django default) |
The absolute filesystem path to the directory that will hold user-uploaded media files. |
SECRET_KEY |
String |
(Django required) |
A secret key used for cryptographic signing, crucial for security (e.g., sessions, password resets). |
ALLOWED_HOSTS |
List/String |
[] |
A list of strings representing the host/domain names that this Django site can serve. Protects against HTTP Host header attacks. |
STARTUP_RUN_MIGRATIONS |
Boolean |
True |
If set to True, Django database migrations will be automatically applied when the container starts. |
OASIS_ADMIN_USER |
String |
None |
If set, a default Django superuser will be created with this username. Requires OASIS_ADMIN_PASS. |
OASIS_ADMIN_PASS |
String |
None |
The password for the default admin user specified by OASIS_ADMIN_USER. Requires OASIS_ADMIN_USER. |
Debug Options¶
Option Name |
Type |
Default |
Description |
---|---|---|---|
DEBUG |
Boolean |
False |
Controls Django’s debug mode. If True, enables verbose logging, error pages, and other development features. Should be False in production. |
DEBUG_TOOLBAR |
Boolean |
False |
If True, enables the Django Debug Toolbar, typically accessible in the Swagger UI for development and debugging purposes. |
URL_SUB_PATH |
Boolean |
False |
If True, all REST API routes will be nested under a /api/ sub-path (e.g., https://<site-domain>/api/). Otherwise, routes are directly under the domain (e.g., https://<site-domain>/). |
DISABLE_V2_API |
Boolean |
False |
If True, disables the V2 API routes, primarily for backward compatibility with older client integrations. |
Server Database (DB) Options¶
Option Name |
Type |
Default |
Description |
---|---|---|---|
DB_ENGINE |
String |
django.db.backends.postgresql_psycopg2 |
The database backend engine (e.g., django.db.backends.postgresql_psycopg2, django.db.backends.mysql). |
DB_HOST |
String |
localhost |
The hostname or IP address of the database server. |
DB_PASS |
String |
None |
The password for the database user. |
DB_USER |
String |
None |
The username for connecting to the database. |
DB_NAME |
String |
oasis |
The name of the database to connect to. |
DB_PORT |
Integer |
5432 |
The port number on which the database server is listening. (e.g., 5432 for PostgreSQL, 3306 for MySQL). |
CHANNEL_LAYER_HOST |
String |
channel-layer |
The hostname or IP address of the server hosting the Django Channels layer (e.g., Redis or RabbitMQ). |
Authentication Options¶
Option Name |
Type |
Default |
Description |
---|---|---|---|
API_AUTH_TYPE |
String |
simple_jwt |
Defines the API authentication mechanism. Valid values are ‘keycloak’ or ‘simple_jwt’. |
If API_AUTH_TYPE is ‘keycloak’, the following options are valid:
Option Name |
Type |
Default |
Description |
---|---|---|---|
OIDC_CLIENT_NAME |
String |
None |
The client ID registered with the Keycloak (OpenID Connect) server. |
OIDC_CLIENT_SECRET |
String |
None |
The client secret for the Keycloak (OpenID Connect) client. |
OIDC_ENDPOINT |
String |
None |
The base URL of the Keycloak (OpenID Connect) server’s discovery endpoint (e.g., https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration). |
If API_AUTH_TYPE is ‘simple_jwt’, the following options are valid:
Option Name |
Type |
Default |
Description |
---|---|---|---|
ACCESS_TOKEN_LIFETIME |
String |
1h (1 hour) |
The duration for which access tokens are valid before expiring. Examples: 1h, 15m, 30s. |
REFRESH_TOKEN_LIFETIME |
String |
2days (2 days) |
The duration for which refresh tokens are valid. Used to obtain new access tokens. Examples: 2days, 1w. |
ROTATE_REFRESH_TOKENS |
Boolean |
True |
If True, a new refresh token will be issued each time a refresh token is used, invalidating the old one. Enhances security. |
BLACKLIST_AFTER_ROTATION |
Boolean |
True |
If True, used refresh tokens are added to a blacklist, preventing their reuse after rotation. |
SIGNING_KEY |
String |
SECRET_KEY |
The key used for signing JWT tokens. If not explicitly set, Django’s SECRET_KEY will be used. Should be a strong, unique secret. |
Worker Container Configuration Options¶
These options are specifically applicable to the worker (Celery) container, which processes tasks dispatched from the API.
Celery Queue Naming¶
These three variables are crucial for the worker to correctly identify and connect to its designated Celery task queue. They must match the corresponding values used by the API’s models endpoint when dispatching tasks.
Option Name |
Type |
Default |
Description |
---|---|---|---|
MODEL_SUPPLIER_ID |
String |
None |
Identifier for the model supplier, forming part of the Celery queue name. |
MODEL_ID |
String |
None |
Identifier for the specific model, forming part of the Celery queue name. |
MODEL_VERSION_ID |
String |
None |
Identifier for the model version, forming part of the Celery queue name. |
Workflow Run Mode¶
Option Name |
Type |
Default |
Description |
---|---|---|---|
RUN_MODE |
String |
None |
Determines the worker’s operational mode. - ‘v1’: Selects a single-server, legacy workflow. - ‘v2’: Selects distributed, modern workflow based on the OASIS platform. |
Worker Paths¶
These options define file locations within the worker container for models, configuration, and run data.
Option Name |
Type |
Default |
Description |
---|---|---|---|
MODEL_SETTINGS_FILE |
String |
/home/worker/model/meta-data/model_settings.json |
The absolute path to the model_settings.json meta file, containing model-specific configuration. |
OASISLMF_CONFIG |
String |
/home/worker/model/oasislmf.json |
The absolute path to the oasislmf.json configuration file, used by the OASIS LMF library. |
MODEL_DATA_DIRECTORY |
String |
/home/worker/model |
The absolute path to the directory containing model data. |
BASE_RUN_DIR |
String |
/tmp/run |
The base directory where temporary run files and results are stored during task execution. |
TASK_LOG_DIR |
String |
/var/log/oasis/tasks |
The directory where specific logs for individual tasks executed by the worker are stored. |
Debug Options¶
These options control various debugging behaviors and features within the worker.
Option Name |
Type |
Default |
Description |
---|---|---|---|
DEBUG |
Boolean |
False |
If True, enables increased and more verbose logging for worker operations, useful for debugging. |
DISABLE_WORKER_REG |
Boolean |
False |
If True, disables the worker’s automatic self-registration process with the API server’s ‘models’ endpoint upon connection. |
V2 Mode Only Options¶
These options are only relevant and applied when RUN_MODE is set to ‘v2’.
Option Name |
Type |
Default |
Description |
---|---|---|---|
KEEP_LOCAL_DATA |
Boolean |
False |
If True, the worker will retain local temporary data generated during task execution after the task completes. |
KEEP_REMOTE_DATA |
Boolean |
False |
If True, the worker will retain remote data (e.g., in object storage) generated during task execution after the task completes. |
FAIL_ON_REDELIVERY |
Boolean |
True |
A safeguard mechanism. If True, the worker checks if a task has been previously attempted. If a task has been redelivered (attempted multiple times, e.g., 3 times), it will mark the task as failed. |
V1 Mode Only Options¶
These options are only relevant and applied when RUN_MODE is set to ‘v1’.
Option Name |
Type |
Default |
Description |
---|---|---|---|
KEEP_RUN_DIR |
Boolean |
False |
If True, the temporary run directories created for tasks will not be deleted after the task completes, remaining within the container. |
LOCK_FILE |
String |
/tmp/tmp_lock_file |
The absolute path to a lock file used to prevent multiple jobs from executing concurrently on the same machine/worker instance. |
LOCK_TIMEOUT_IN_SECS |
Integer |
None |
The maximum time in seconds to wait for the LOCK_FILE to become available before a task gives up trying to acquire the lock. |
LOCK_RETRY_COUNTDOWN_IN_SECS |
Integer |
None |
The time in seconds to wait before retrying to acquire the LOCK_FILE if it is currently held. |
Storage Related Options¶
These options configure the worker’s ability to interact with various storage backends for input/output data.
Option Name |
Type |
Default |
Description |
---|---|---|---|
STORAGE_TYPE |
String |
shared-fs |
Defines the backend storage solution. Valid values are ‘S3’ (AWS S3), ‘AZURE’ (Azure Blob Storage), or ‘shared-fs’ (a common file system accessible by containers). |
If STORAGE_TYPE is ‘S3’, the following options are valid:
Option Name |
Type |
Default |
Description |
---|---|---|---|
AWS_ACCESS_KEY_ID |
String |
None |
Your AWS access key ID. Required for S3 authentication. |
AWS_SECRET_ACCESS_KEY |
String |
None |
Your AWS secret access key. Required for S3 authentication. |
AWS_BUCKET_NAME |
String |
None |
The name of the S3 bucket where files will be stored or retrieved by the worker. |
AWS_SHARED_BUCKET |
String |
None |
(Inferred) Specifies a shared S3 bucket name if multiple components access the same shared storage. |
AWS_LOCATION |
String |
None |
The base path or directory within the S3 bucket where worker-related files are stored. |
AWS_QUERYSTRING_EXPIRE |
Integer |
3600 |
The expiration time in seconds for signed S3 URLs generated by the worker. |
AWS_QUERYSTRING_AUTH |
Boolean |
True |
If True, generated URLs for S3 objects will include query string authentication. |
AWS_LOG_LEVEL |
String |
INFO |
Logging level for AWS S3 operations performed by the worker. |
If STORAGE_TYPE is ‘AZURE’, the following options are valid:
Option Name |
Type |
Default |
Description |
---|---|---|---|
AZURE_ACCOUNT_NAME |
String |
None |
Your Azure Storage account name. Required for Azure Blob Storage. |
AZURE_ACCOUNT_KEY |
String |
None |
Your Azure Storage account key. Required for Azure Blob Storage. |
AZURE_CONTAINER |
String |
None |
The name of the Azure Blob Storage container where files will be stored or retrieved by the worker. |
AZURE_LOCATION |
String |
None |
The base path or virtual directory within the Azure container where worker-related files are stored. |
AZURE_SHARED_CONTAINER |
String |
None |
(Inferred) Specifies a shared Azure container name if multiple components access the same shared storage. |
AZURE_LOG_LEVEL |
String |
INFO |
Logging level for Azure Blob Storage operations performed by the worker. |
AZURE_SSL |
Boolean |
True |
If True, secure SSL connections will be used for Azure Blob Storage. |
AZURE_UPLOAD_MAX_CONN |
Integer |
2 |
The maximum number of concurrent connections to use for Azure Blob uploads. |
AZURE_CONNECTION_TIMEOUT_SECS |
Integer |
20 |
The timeout in seconds for Azure Blob Storage connections. |
AZURE_URL_EXPIRATION_SECS |
Integer |
3600 |
The expiration time in seconds for generated shared access signature (SAS) URLs for Azure blobs. |
AZURE_CONNECTION_STRING |
String |
None |
A full Azure Storage connection string. Can be used as an alternative to AZURE_ACCOUNT_NAME and AZURE_ACCOUNT_KEY. |
AZURE_TOKEN_CREDENTIAL |
String |
None |
(Inferred) A token credential for authentication with Azure Blob Storage, typically for OAuth/Managed Identity. |
AZURE_CACHE_CONTROL |
String |
None |
Value for the Cache-Control header on uploaded Azure blobs. |
AZURE_OBJECT_PARAMETERS |
JSON/String |
None |
(Inferred) Additional parameters to apply to Azure blob objects on upload, typically as a JSON string. |
Celery Configuration Options¶
The following options apply to both server and worker containers, any container connected to celery. But can vary by oasis version.
Celery Broker: Image Versions 1.28.x or Older¶
Option Name |
Type |
Default |
Description |
---|---|---|---|
OASIS_RABBIT_HOST |
String |
broker |
Hostname of the RabbitMQ broker for Celery workers. |
OASIS_RABBIT_PORT |
Integer |
5672 |
Port of the RabbitMQ broker for Celery workers. |
OASIS_RABBIT_USER |
String |
rabbit |
Username for connecting to the RabbitMQ broker for Celery workers. |
OASIS_RABBIT_PASS |
String |
rabbit |
Password for connecting to the RabbitMQ broker for Celery workers. |
Celery Broker: Image Versions 2.3.x or Newer¶
Option Name |
Type |
Default |
Description |
---|---|---|---|
OASIS_CELERY_BROKER_URL |
String |
amqp://rabbit:rabbit@broker:5672 |
Full connection URL for the Celery broker. |
Celery Results DB connection Values: Applies to All Versions¶
Option Name |
Type |
Default |
Description |
---|---|---|---|
CELERY_DB_ENGINE |
String |
db+postgresql+psycopg2 |
Specifies the database engine for Celery’s results backend. |
CELERY_DB_HOST |
String |
celery-db |
Hostname for the database used as Celery’s results backend. |
CELERY_DB_PASS |
String |
password |
Password for accessing the database used as Celery’s results backend. |
CELERY_DB_USER |
String |
celery |
Username for accessing the database used as Celery’s results backend. |
CELERY_DB_NAME |
String |
celery |
Name of the database used as Celery’s results backend. |
CELERY_DB_PORT |
Integer |
5432 |
Port for connecting to the database used as Celery’s results backend. |
Celery concurrency and custom arguments¶
The Following apply only to the worker images, and are not configurable from the conf.ini file
Option Name |
Type |
Default |
Description |
---|---|---|---|
OASIS_CELERY_CONCURRENCY |
Integer |
Number of available cores |
Sets the concurrency argument for Celery workers. By default, it equals the number of available cores, but can be set lower to mitigate out-of-memory errors. |
OASIS_CELERY_EXTRA_ARGS |
String |
None |
Allows passing custom Celery arguments directly into the worker’s startup command. Refer to the Celery CLI documentation for available options. |