GAIA API configuration can be found in config/config.py, as the extension implies it is a python file, making it configurable, meaning you can use libraries, constants, calculate keys, dates on the fly, and define environment variables.


Access From Code

This configuration is accessible anywhere in the code doing an import

from config import SERVER_CONFIG

DO NOT CHANGE THE SERVER CONFIG!

You shouldn't change or add any new configuration to this file, only modify the options already available. This configuration is SERVER ONLY, configuration regarding stages belongs to the stage config in their respective packages.


Current Default Configuration Sample

The current default configuration can be found here in case the sample below is outdated config.py 

# ==============================================================================
#  Copyright ©2023 Accenture and/or its affiliates. All Rights Reserved.
#
#  Permission to any use, copy, modify, and distribute this software and its
#  documentation for any purpose is subject to a licensing agreement duly
#  entered into with the copyright owner or its affiliate.
#
#  All information contained herein is, and remains the property of Accenture
#  and/or its affiliates and its suppliers, if any.  The intellectual and
#  technical concepts contained herein are proprietary to Accenture and/or
#  its affiliates and its suppliers and may be covered by one or more patents
#  or pending patent applications in one or more jurisdictions worldwide, and
#  are protected by trade secret or copyright law. Dissemination of this
#  information or reproduction of this material is strictly forbidden unless
#  prior written permission is obtained from Accenture and/or its affiliates.
# ==============================================================================

#
#
import os
from os.path import join

from models.engines import Authentications, EngineTypes
from models.security import AuthenticationType
from utils.constants import DEFAULT_ENGINE_NAME, SERVER_PATH
from utils.str import DEFAULT_ENCODING

os.environ['UVICORN_WORKERS'] = os.getenv('UVICORN_WORKERS', default='1')
os.environ['PORT'] = os.getenv('PORT', default='8085')
os.environ['HOST'] = os.getenv('HOST', default='0.0.0.0')
os.environ['DOMAIN_NAME'] = os.getenv('DOMAIN_NAME', default='localhost')
os.environ['COOKIE_DOMAIN_NAME'] = os.getenv('COOKIE_DOMAIN_NAME', default='')

os.environ['ENGINE_URL'] = os.getenv('ENGINE_URL', default='http://localhost:9200')

# *******************************************************************************
# AWS Elasticsearch Credentials
# *******************************************************************************

# Domain. If service is set then the AWS will be used
# os.environ['AWS_SERVICE'] = os.getenv('AWS_SERVICE', default='es')
# os.environ['AWS_REGION'] = os.getenv('AWS_REGION', default='us-east-1')

# ------------------------------------------------------
# Uncomment only if using Access Key and Session Token
# ------------------------------------------------------

# os.environ['AWS_ACCESS_KEY_ID'] = os.getenv('AWS_ACCESS_KEY_ID', default='default-key')
# os.environ['AWS_SECRET_ACCESS_KEY'] = os.getenv('AWS_SECRET_ACCESS_KEY', default='default-secret')
# os.environ['AWS_SESSION_TOKEN'] = os.getenv('AWS_SESSION_TOKEN', default='default-token')

CONFIG = {
    'host': os.getenv('HOST'),
    'port': os.getenv('PORT'),
    'workers': os.getenv('UVICORN_WORKERS'),
	'generate_settings_docs': True,
     'cors': {
        'allow_origins': [
            'https://login.microsoftonline.com',
            f'http://{os.getenv("DOMAIN_NAME")}:{os.getenv("PORT")}',
            f'http://{os.getenv("DOMAIN_NAME")}:3000',
            f'https://{os.getenv("DOMAIN_NAME")}:{os.getenv("PORT")}',
            f'https://{os.getenv("DOMAIN_NAME")}:3000'
        ],
        'allow_credentials': True,
        'allow_methods': ['*'],
        'allow_headers': ['*'],
        'expose_headers': ['*'],
        'max_age': 600
    },

    'web_app_config': {
        'title': '',
        'description': '',
        'default_lang': 'en',
        'available_langs': ['en'],
        'default_webview': 'config',
        'web_views': ['config'],
    },

    'logging': {
        'msgFormat': '%(asctime)s\t%(levelname)s\t%(name)s\t%(message)s',
        'dateFormat': '%Y-%m-%dT%H:%M:%S%z',
        'level': 'STAT',
        'handlers': {
            'file': {
                'enable': True,
                'encoding': DEFAULT_ENCODING,
                'backupCount': 5,
                'maxBytes': 5242880,  # 5Mb
            },
            'console': {
                'enable': True
            },
            'nonSQL': {
                'enable': True
            }
        },
        'loggers': {
            'werkzeug': 'info',
            'django.utils.autoreload': 'warning',
            'ldap3': 'info',
            'fastapi': 'notset',
            'passlib.utils.compat': 'info',
            'urllib3.connectionpool': 'info',
            'passlib.registry': 'info',
            'app.rest': 'info',
            'uvicorn.error': 'error'
        }
    },

    # *******************************************************************************
    #  Engines Configuration for ES features
    # *******************************************************************************
    'engines': [
        {
            'name': DEFAULT_ENGINE_NAME,  # Name of the connection
            'type': EngineTypes.ELASTIC,  # EngineType is an enum with the available engine types
            'default': True,
            'headers': {
                'Accept-Encoding': 'gzip'
            },
            'engine_url': os.getenv('ENGINE_URL').split(),
            'index_prefix': 'gaia',
            'pool_connections': 10,
            'pool_maxsize': 100,
            'pool_block': True,
            'verify': False,
            'max_redirects': 30,
            'max_retries': 10,
            'retry_wait_time': 10,
            'timeout': 60,
            'allow_redirects': True,
            'trust_env': True,
            'use_throttling': True,
            'throttling_rate': 5000,
            'throttling_connection_rate': 50,
            'auth': {
                'type': Authentications.BASIC,

                # With Authentications.BASIC
                # #### For Basic Auth ####
                'username': os.getenv('ENGINE_USER'),
                'password': os.getenv('ENGINE_PASSWORD')

                # With Authentications.AWS
                # #### For AWS Auth ####
                # 'aws_region': os.getenv('AWS_REGION'),
                # 'aws_service': os.getenv('AWS_SERVICE'),
                # 'aws_access_key': os.getenv('AWS_ACCESS_KEY_ID'),
                # 'aws_secret_key': os.getenv('AWS_SECRET_ACCESS_KEY')

                # With Authentications.AWS
                # #### For AWS Auth With Credentials Provider (AWS)####
                # 'credentials_provider': True,
                # 'aws_region': os.getenv('AWS_REGION'),
                # 'aws_service': os.getenv('AWS_SERVICE')

            },
            'log_requests': False
        }
    ],

    # *******************************************************************************
    # Security Configuration
    # *******************************************************************************
    'security': {

        # *******************************************************************************
        # Authentication
        # *******************************************************************************
        'authentication': {
            'enabled': False,
            'type': AuthenticationType.OIDC,
            'secret': os.getenv('AUTH_SECRET', default='52ecfd60e01b800355a8ce59780f9243b4662c3a236394ee'),
            'force_https_original_url_redirection': False,

            'anonymous': {
                'id': 'Anonymous',
                'account': '[email protected]',
                'name': 'Anonymous',
                'displayName': 'Anonymous'
            },
            # *******************************************************************
            # Local Authentication based on a CSV implements FORM and BASIC Auth
            #
            # NOTE: Only recommended for testing
            # *******************************************************************
            'local': {
                'file': join(SERVER_PATH, 'config', 'auth', 'users.csv')
            },

            # **************************************
            # DELEGATED Authentication
            # **************************************

            'delegated': {
                'jwks_url': os.getenv('DELEGATE_JWKS_URL'),
                'audience': 'AudienceIDMPrototype',
                'attributesMapping': {
                    # key is the property name stored in the GAIA user profile,
                    # the value is the user attribute in LDAP

                    'id': 'email',  # _id is required
                    'account': 'email',  # account is for roles and group expansion
                }
            },

            # **************************************
            # LDAP Authentication
            # **************************************
            'ldap': {
                'authentication': 'SIMPLE',
                'url': os.getenv('LDAP_URL'),
                'bindDN': 'uid=admin,ou=system',  # Bind DN or User
                'bindCredentials': os.getenv('LDAP_CREDENTIALS'),  # password
                'searchBase': 'ou=users,ou=system',
                'searchFilter': '(uid=%s)',
                'searchAttributes': ['uid', 'cn', 'sn', 'displayName'],
                'attributesMapping': {
                    # key is the property name stored in the GAIA user profile,
                    # the value is the user attribute in LDAP

                    'id': 'uid',  # _id is required
                    'account': 'uid',  # account is for roles and group expansion
                    'email': 'uid',
                    'firstName': 'cn',
                    'lastName': 'sn',
                    'name': 'cn',
                    'displayName': 'alias',
                    # if the alias is not given, one is created from the first and last name or roles
                    'groups': 'ou',
                    'photo': 'photo'
                }
            },

            # **************************************
            # OIDC Authentication
            # **************************************
            'oidc': {
                'client_id': os.getenv('OIDC_CLIENT_ID'),
                # Audience can be omitted in which case the aud value defaults to client_id
                'openid_configuration_uri': os.getenv('OIDC_OPENID_CONFIG_URI'),
                'attributesMapping': {
                    'id': 'oid',
                    'account': 'email'
                },
                'json_redirect': False,
                'cookie': {
                    'path': '/',
                    'samesite': 'lax',
                    'httponly': False,
                    'secure': False,
                    'domain': os.getenv('COOKIE_DOMAIN_NAME')
                }
            }
        },

        # *******************************************************************************
        # Encryption
        # *******************************************************************************
        'encryption': {
            'secret_key': join(SERVER_PATH, 'config', 'auth', 'secret_key')
        },

        # *******************************************************************************
        # Roles
        # ******************************************************************************
        'roles': {
            'file': join(SERVER_PATH, 'config', 'auth', 'roles.csv')
        },

        # *******************************************************************************
        # Include Headers.
        # Headers on this section will be added to all responses of the api
        # ******************************************************************************
        'headers': {
            'include': [
                ('strict-transport-security', 'max-age=31536000;includeSubDomains')
            ]
        }
    },

    # *******************************************************************************
    # Mailer
    # *******************************************************************************
    'mailer': {
        'enable': False,  # Enables an endpoint for direct access through http request
        'mailer_config': {
            # **********************
            # Using Gmail
            # **********************
            'service': 'gmail',
            'auth': {
                'user': '[email protected]',
                'password': 'test'
            }

            # **********************
            # Using a Custom SMTP
            # **********************
            # 'host': os.getenv('SMTP_RELAY', default='localhost'),
            # 'port': os.getenv('SMTP_PORT', default=22),
            # 'secure': False,
            # 'logger': True,
            # 'debug': True,
            # 'tls': {
            #    'ca':[ Path(os.getenv('CERTIFICATES_PATH')).read_text() ],
            #    'rejectUnauthorized': False,
            # },
        },
        'from': '[email protected]',  # From to display in the email
        'test': True,  # send the emails to the to_test_email, instead to the actual destiny
        'to_test_email': '[email protected]',  # Test destination for all email send
        'default_subject': 'Email Suibject',  # default subject, if none is specified in code
        'data': {
            # This body will be injected as _data, un the actual, body used to map the email
            # templates (e.g {{{_data.url}}})
            'url': 'http://example.com/'
        },

        # **********************
        # Templates
        # **********************
        'plain_template_path': join(SERVER_PATH, 'config', 'templates', 'email_text.tlp'),
        'html_template_path': join(SERVER_PATH, 'config', 'templates', 'email_html.tlp')
    },

    # *****************************************************************************************
    # Analytics Logs all activity in the UI, and activity triggered by the user in the Server
    # *****************************************************************************************
    'analytics': {
        'enable': True
    }
}
    

Configuration Sections

Starting with a reminder, the configuration file is a .py file, which means you can code in it, making a more dynamic configuration, and that’s what we did.


Imports

Imports for the utility function used on the configuration creation

python
from os.import os
from os.path import join

from models.engines import Authentications, EngineTypes
from models.security import AuthenticationType
from utils.constants import DEFAULT_ENGINE_NAME, SERVER_PATH
from utils.str import DEFAULT_ENCODING import join
from models.engines import Authentications, EngineTypes
from models.security import AuthenticationType
from utils.constants import DEFAULT_ENGINE_NAME, SERVER_PATH
from utils.str import DEFAULT_ENCODING

Environment Variable

The configuration file sets several environment variables to configure the application's behavior. These variables are essential for defining network settings and integration parameters.

NameDefaultDescription
UVICORN_WORKERS1

Number of Uvicorn workers.

  • Applicable only when using the provided uvicorn server
  • If using default server, the workers should be set according to the project needs
PORT'8085'Port number for the application.
HOST'0.0.0.0'Host IP address for the application.
DOMAIN_NAME'localhost'Domain name used for the application.
COOKIE_DOMAIN_NAME'' (empty)Domain name for setting cookies.
ENGINE_URL'http://localhost:9200'URL for the application engine.
python
os.environ['UVICORN_WORKERS'] = os.getenv('UVICORN_WORKERS', default=1)
os.environ['PORT'] = os.getenv('PORT', default='8085')
os.environ['HOST'] = os.getenv('HOST', default='0.0.0.0')
os.environ['DOMAIN_NAME'] = os.getenv('DOMAIN_NAME', default='localhost')
os.environ['COOKIE_DOMAIN_NAME'] = os.getenv('COOKIE_DOMAIN_NAME', default='')
os.environ['ENGINE_URL'] = os.getenv('ENGINE_URL', default='http://localhost:9200')

AWS Elasticsearch Credentials (Commented)

Commented-out AWS Elasticsearch credentials, to be used if the AWS service is chosen.

NameDefaultDescription
AWS_SERVICE'es'The AWS service name, defaulting to Elasticsearch.
AWS_REGION'us-east-1'The AWS region.
AWS_ACCESS_KEY_ID'default-key'AWS Access Key ID.
AWS_SECRET_ACCESS_KEY'default-secret'AWS Secret Access Key.
AWS_SESSION_TOKEN'default-token'AWS Session Token.
python
# os.environ['AWS_SERVICE'] = os.getenv('AWS_SERVICE', default='es')
# os.environ['AWS_REGION'] = os.getenv('AWS_REGION', default='us-east-1')
# os.environ['AWS_ACCESS_KEY_ID'] = os.getenv('AWS_ACCESS_KEY_ID', default='default-key')
# os.environ['AWS_SECRET_ACCESS_KEY'] = os.getenv('AWS_SECRET_ACCESS_KEY', default='default-secret')
# os.environ['AWS_SESSION_TOKEN'] = os.getenv('AWS_SESSION_TOKEN', default='default-token')

CONFIG Variable

The CONFIG variable is a central configuration object that consolidates various settings and options for the application. This structured dictionary contains nested sections, each representing specific aspects of configuration, such as server parameters, security settings, and more. It enhances code readability and flexibility by providing a clear and organized way to customize the script's behavior without extensive code changes.

General Configuration (host, port, workers)

General settings include host IP, port number, and number of Uvicorn workers.

python
CONFIG = {
    'host': os.getenv('HOST'),
    'port': os.getenv('PORT'),
    'workers': os.getenv('UVICORN_WORKERS'),
    'generate_settings_docs': True,
     # ... (other configurations)
}
NameTypeDefaultDescription
hostStringlocalhostHost to which the server will be listening
portInteger8085Port in which the server will be listening
workersInteger1Number to workers for the webapp
generate_settings_docsBooleanTrueIf true, GAIA API will seach and generate html documentation for each data model, accessible via http://localhost:8085/es/docs/schemas/config

CORS Configuration

Manages Cross-Origin Resource Sharing settings.

NameTypeDefaultDescription
allow_originsList
A list of allowed origins (URLs) that can access the server.
allow_credentialsBooleanTrueIndicates whether the server allows credentials (e.g., cookies, HTTP authentication) to be included in cross-origin requests.
allow_methodsList['*']A list of HTTP methods (e.g., GET, POST) that are allowed for cross-origin requests. Use ['*'] to allow all methods.
allow_headersList['*']A list of HTTP headers that are allowed for cross-origin requests. Use ['*'] to allow all headers.
expose_headersList['*']A list of HTTP headers that are exposed to the response of cross-origin requests. Use ['*'] to expose all headers.
max_ageInteger600The maximum time (in seconds) that the results of a preflight request (OPTIONS) can be cached.
python
'cors': {
    'allow_origins': [
         'https://login.microsoftonline.com',
         f'http://{os.getenv("DOMAIN_NAME")}:{os.getenv("PORT")}',
         f'http://{os.getenv("DOMAIN_NAME")}:3000',
         f'https://{os.getenv("DOMAIN_NAME")}:{os.getenv("PORT")}',
         f'https://{os.getenv("DOMAIN_NAME")}:3000'
    ],
    'allow_credentials': True,
    'allow_methods': ['*'],
    'allow_headers': ['*'],
    'expose_headers': ['*'],
    'max_age': 600
},

Web App Configuration

Settings related to the web application's interface.

NameTypeDefaultDescription
titleString''Title of the web app.
descriptionString''App description.
default_langString'en'Default language.
available_langsList['en']List of available languages.
default_webviewString'config'Default web view.
web_viewsList['config']List of web views.
python
'web_app_config': {
    'title': '',
    'description': '',
    'default_lang': 'en',
    'available_langs': ['en'],
    'default_webview': 'config',
    'web_views': ['config'],
},

Logging Configuration

Specifies details for logging.

NameTypeDefaultDescription
msgFormatstr-Log message format string
dateFormatstr-Date format for log messages
levelstr'STAT'Logging level (e.g., 'DEBUG', 'STAT', 'INFO', 'ERROR', 'CRITICAL')
handlersdict-Dictionary of log handlers
handlers.filedict-File log handler configuration
handlers.file.enableboolTrueEnable file log handler
handlers.file.encodingstr'UTF-8'File encoding for log files
handlers.file.backupCountint5Number of log file backups to keep
handlers.file.maxBytesint5242880 (5MB)Maximum log file size (bytes)
handlers.consoledict-Console log handler configuration
handlers.console.enableboolTrueEnable console log handler
handlers.nonSQLdict-

Non-SQL log handler configuration

Non-SQL starts recording after the connection to the engine was made

handlers.nonSQL.enableboolTrueEnable non-SQL log handler
loggersdict-Dictionary of logger configurations
loggers.werkzeugstr'info'Werkzeug logger level
loggers.django.utils.autoreloadstr'warning'Django autoreload logger level
loggers.ldap3str'info'LDAP3 logger level
loggers.fastapistr'notset'FastAPI logger level
loggers.passlib.utils.compatstr'info'Passlib utils compat logger level
loggers.urllib3.connectionpoolstr'info'Urllib3 connection pool logger level
loggers.passlib.registrystr'info'Passlib registry logger level
loggers.app.reststr'info'App rest logger level
loggers.uvicorn.errorstr'error'Uvicorn error logger level
python
'logging': {
    'msgFormat': '%(asctime)s\t%(levelname)s\t%(name)s\t%(message)s',
    'dateFormat': '%Y-%m-%dT%H:%M:%S%z',
    'level': 'INFO',
    'handlers': {
        'file': {
            'enable': True,
            'encoding': DEFAULT_ENCODING,
            'backupCount': 5,
            'maxBytes': 5242880,  # 5Mb
        },
        'console': {
            'enable': True
        },
        'nonSQL': {
            'enable': True
        }
    },
    'loggers': {
        'werkzeug': 'info',
        'django.utils.autoreload': 'warning',
        'ldap3': 'info',
        'fastapi': 'notset',
        'passlib.utils.compat': 'info',
        'urllib3.connectionpool': 'info',
        'passlib.registry': 'info',
        'app.rest': 'info',
        'uvicorn.error': 'error'
    }
},

Engines Configuration

List of search engine connections to handle, all the connections can be accessed via the connection manager, across the code

NameTypeDefaultDescription
namestr

Name of the connection

You can add the name as a constant in the file utils/constants/__init__.py, that way you can reference your engine name anywhere in the code

typeEnum

Type of the engine (e.g., EngineTypes.ELASTIC)

Use enum class EngineTypes, you can import EngineType with 

from models.engines import EngineTypes
defaultbool
Indicates if it's the default engine
headersdict
Headers to include in requests to the engine
engine_urllist
List of engine URLs (may be multiple)
index_prefixstr
Prefix for Elasticsearch index names
pool_connectionsint
Number of connections in the connection pool
pool_maxsizeint
Maximum size of the connection pool
pool_blockbool
Whether to block when the pool is full
verifybool
Verify SSL certificates (False to disable)
max_redirectsint
Maximum number of redirects to follow
max_retriesint
Maximum number of retries on request failure
retry_wait_timeint
Time to wait between retries (in seconds)
timeoutint
Request timeout (in seconds)
allow_redirectsbool
Allow redirects in requests
trust_envbool
Trust environment variables for configuration
use_throttlingbool
Enable throttling for this engine
throttling_rateint
Request rate limit for throttling (requests/sec)
throttling_connection_rateint
Connection rate limit for throttling (connections/sec)
authdict
Authentication configuration for this engine
log_requestsbool
Log HTTP requests (True to enable)

You can get a more detailed explanation in Engine Framework

python
'engines': [
    {
        'name': DEFAULT_ENGINE_NAME,
        'type': EngineTypes.ELASTIC,
        'default': True,
        'headers': {
            'Accept-Encoding': 'gzip'
        },
        'engine_url': os.getenv('ENGINE_URL').split(),
        'index_prefix': 'gaia',
        'pool_connections': 10,
        'pool_maxsize': 100,
        'pool_block': True,
        'verify': False,
        'max_redirects': 30,
        'max_retries': 10,
        'retry_wait_time': 10,
        'timeout': 60,
        'allow_redirects': True,
        'trust_env': True,
        'use_throttling': True,
        'throttling_rate': 5000,
        'throttling_connection_rate': 50,
        'auth': {
            'type': Authentications.NONE,

             # With Authentications.BASIC
             # #### For Basic Auth ####
             # 'username': os.getenv('ENGINE_USER'),
             # 'password': os.getenv('ENGINE_PASSWORD')

             # With Authentications.AWS
             # #### For AWS Auth ####
             # 'aws_region': os.getenv('AWS_REGION'),
             # 'aws_service': os.getenv('AWS_SERVICE'),
             # 'aws_access_key': os.getenv('AWS_ACCESS_KEY_ID'),
             # 'aws_secret_key': os.getenv('AWS_SECRET_ACCESS_KEY')

             # With Authentications.AWS
             # #### For AWS Auth With Credentials Provider (AWS)####
             # 'credentials_provider': True,
             # 'aws_region': os.getenv('AWS_REGION'),
             # 'aws_service': os.getenv('AWS_SERVICE')
         },
        'log_requests': False
    }
],

Security Configuration

Handles various security aspects of the application.


NameTypeDefaultDescription
authentication.enabledboolFalseIndicates whether authentication is enabled.
authentication.typestrOIDCThe type of authentication mechanism to use (e.g., OIDC, local, delegated, ldap).
authentication.secretstr52ecfdThe secret key used for authentication (e.g., for OIDC).

authentication.
force_https_original_url_redirection

boolFalseSpecifies whether to force HTTPS original URL redirection when using OIDC.
authentication.anonymous.
id		strAnonymousThe ID for anonymous users.
authentication.anonymous.
account		str[email protected]The account name for anonymous users.
authentication.anonymous.
name		strAnonymousThe name of anonymous users.
authentication.anonymous.
displayName		strAnonymousThe display name of anonymous users.
authentication.localobject'config/auth/users.csv'This section of the configuration deals with local authentication based on a CSV file. Local authentication allows users to log in using credentials stored in a CSV file
authentication.delegatedobjectobjectThis section of the configuration deals with delegated authentication, specifically using the OAuth 2.0 protocol. Delegated authentication allows users to log in to your application using their existing accounts with external identity providers
authentication.ldapobject
This section of the configuration deals with LDAP (Lightweight Directory Access Protocol) authentication. LDAP is a protocol used for authenticating and authorizing users by accessing a directory service
authentication.oidcobject
The client ID for OIDCThis section of the configuration is related to OIDC (OpenID Connect) authentication. OIDC is an authentication protocol that builds on top of OAuth 2.0 and provides user authentication as well as information about the user. .
encryption.secret_keystr'config/auth/secret_key'The path to the secret key used for encryption.
roles.filestr'config/auth/roles.csv'The file path for roles configuration.
headers.includelist[(
'strict-transport-security',
'maxage=31536000;
includeSubDomains'
)]		The list of headers to include in all API responses.
python
'security': {

    # *******************************************************************************
    # Authentication
    # *******************************************************************************
    'authentication': {
        'enabled': False,
        'type': AuthenticationType.OIDC,
        'secret': '52ecfd',
        'force_https_original_url_redirection': False,

        'anonymous': {
            'id': 'Anonymous',
            'account': '[email protected]',
            'name': 'Anonymous',
            'displayName': 'Anonymous'
        },
        # *******************************************************************
        # Local Authentication based on a CSV implements FORM and BASIC Auth
        #
        # NOTE: Only recommended for testing
        # *******************************************************************
        'local': {
            # ...
        },

        # **************************************
        # DELEGATED Authentication
        # **************************************

        'delegated': {
            # ...
        },

        # **************************************
        # LDAP Authentication
        # **************************************
        'ldap': {
            # ...
        },

        # **************************************
        # OIDC Authentication
        # **************************************
        'oidc': {
            # ...
        }
    },

    # *******************************************************************************
    # Encryption
    # *******************************************************************************
    'encryption': {
        'secret_key': join(SERVER_PATH, 'config', 'auth', 'secret_key')
    },

    # *******************************************************************************
    # Roles
    # ******************************************************************************
    'roles': {
        'file': join(SERVER_PATH, 'config', 'auth', 'roles.csv')
    },

    # *******************************************************************************
    # Include Headers.
    # Headers on this section will be added to all responses of the api
    # ******************************************************************************
    'headers': {
        'include': [
            ('strict-transport-security', 'max-age=31536000;includeSubDomains')
        ]
    }
},

You can get a more detail explanation in Security 

Mailer Configuration

The 'mailer' configuration section is responsible for configuring email-related settings, including the SMTP service, email templates, and default email settings.

Nested FieldTypeDefaultDescription
enableBooleanFalse (Default)Enables an endpoint for direct access through an HTTP request.
mailer_config.serviceString"gmail" (Default)Specifies the email service provider to use. You can choose between 'gmail' or configure a custom SMTP service.
mailer_config.authObjectN/AContains authentication credentials required for the SMTP service.
mailer_config.hostStringN/A (Uncomment to use)Specifies the SMTP server hostname (uncomment if using a custom SMTP service).
mailer_config.portIntegerN/A (Uncomment to use)Specifies the SMTP server port (uncomment if using a custom SMTP service).
mailer_config.secureBooleanN/A (Uncomment to use)Indicates whether the SMTP connection should be secure (uncomment if using a custom SMTP service).
mailer_config.loggerBooleanN/A (Uncomment to use)Enables SMTP logging (uncomment if using a custom SMTP service).
mailer_config.debugBooleanN/A (Uncomment to use)Enables SMTP debugging (uncomment if using a custom SMTP service).
mailer_config.tlsObjectN/A (Uncomment to use)Defines TLS settings for SMTP (uncomment if using a custom SMTP service).
fromStringN/ASpecifies the email address to display as the sender in outgoing emails.
testBooleanTrueWhen set to True, emails are sent to the 'to_test_email' address instead of the actual recipients for testing purposes.
to_test_emailString"[email protected]" (Default)The email address to which test emails are sent when 'test' mode is enabled.
default_subjectString"Email Subject" (Default)Specifies the default subject for outgoing emails. If not specified in the email content, this subject is used.
dataObjectN/AContains data to be injected into the email content.
plain_template_pathStringN/ASpecifies the file path to the plain text email template.
html_template_pathStringN/ASpecifies the file path to the HTML email template.
python
'mailer': {
    'enable': False,  # Enables an endpoint for direct access through http request
    'mailer_config': {
        # **********************
        # Using Gmail
        # **********************
        'service': 'gmail',
        'auth': {
            'user': '[email protected]',
            'password': 'test'
        }

        # **********************
        # Using a Custom SMTP
        # **********************
        # 'host': os.getenv('SMTP_RELAY', default='localhost'),
        # 'port': os.getenv('SMTP_PORT', default=22),
        # 'secure': False,
        # 'logger': True,
        # 'debug': True,
        # 'tls': {
        #    'ca':[ Path(os.getenv('CERTIFICATES_PATH')).read_text() ],
        #    'rejectUnauthorized': False,
        # },
    },
    'from': '[email protected]',  # From to display in the email
    'test': True,  # send the emails to the to_test_email, instead to the actual destiny
    'to_test_email': '[email protected]',  # Test destination for all email send
    'default_subject': 'Email Suibject',  # default subject, if none is specified in code
    'data': {
        # This body will be injected as _data, un the actual, body used to map the email
        # templates (e.g {{{_data.url}}})
        'url': 'http://example.com/'
    },

    # **********************
    # Templates
    # **********************
    'plain_template_path': join(SERVER_PATH, 'config', 'templates', 'email_text.tlp'),
    'html_template_path': join(SERVER_PATH, 'config', 'templates', 'email_html.tlp')
},

Analytics Configuration

The 'analytics' configuration section is responsible for configuring analytics and logging of all activity in the UI, as well as activity triggered by the user in the server.

NameTypeDefaultDescription
enableboolean-Specifies whether analytics tracking is enabled.
As of version 3.0.0, the Analytics endpoint is not being used by the UI and needs tuning on the development side.  This will be improved in future versions.
python
'analytics': {
    'enable': True
},

Loading the Configuration

From a URL (Using CONFIG_URL Environment Variable)

  • If the CONFIG_URL environment variable is set and not empty.
  • If a valid URL or path to local file is provided, it fetches the configuration content from it

  • Environment variable replacement is performed within the configuration content, when ever a word is contained in  ${}.

    If in the file you got

    {
    "host": "${HOST}"
}

    This will be replace with the environment variable HOST, lets say (HOST=192.168.1.1)

    {
    "host": "192.168.1.1"
}
  • The content is then parsed as JSON

Setting CONFIG_URL as a URL:

In this example, the CONFIG_URL is set to a valid URL (https://example.com/config.json), which points to a remote configuration file hosted on a web server. 

export CONFIG_URL="https://example.com/config.json"

Setting CONFIG_URL as a local file path:

In this example, the CONFIG_URL is set to a local file path (/path/to/local/config.json), which points to a configuration file located on the local file system.

export CONFIG_URL="/path/to/local/config.json"

From the Local File

  • If the CONFIG_URL environment variable is not set or is empty, the configuration is loaded from a local configuration file (config/config.py) and environment variables.
  • It will merge the local configuration with the environment configuration store in config/env if the GAIA_ENV environment file was set to anything other than system_default
    • If the GAIA_ENV is set to production the local config/config.py will be merged with config/env/production.py
  • This method is used as a fallback when no URL is provided, ensuring that the application can run with local configuration.

Environment Configuration Overwrite

If you need to modify configuration for different environments, you need to create this new configuration in config/env. This configuration files can be exactly the same as the default configuration in config/config.py or just fragments of the overwrite configuration needed, like in the example below

from os.path import join

from models.security import AuthenticationType
from utils.constants import SERVER_PATH

CONFIG = {

    'security': {

        'authentication': {
            'enabled': True,
            'type': AuthenticationType.LOCAL,

            'local': {
                'file': join(SERVER_PATH, 'config', 'auth', 'users.csv')
            },
        }
    }
}

This configuration will just overwrite the security authentication section, enabling  the local type authentication and adding the configuration for it, everything else not specified will remain as it is in the default configuration.

No Environment by Default

By default there is not environment set, so only config.py applies


Specify the Environment Configuration

To specify which environment file you want to use, there are 2 options from which to choose, in both cases the environment name must match the name of the environment file

Environment name = Environment File Name

Adding the Environment as an Argument

By adding the argument --env and the name of the environment

Calling script from CMD
python uvicorn_server.py --env=value

Or if executing in docker

Docker CMD
CMD python -m uvicorn app.webapp:app --host 0.0.0.0 --port 8085 --workers 1 --no-server-header --env value


Adding the Environment as a Environment Variable in the OS

By adding the environment variable SA_ENV and the name of the environment

Windows  CMD

To set an environment variable in Windows using CMD, you can use the set command:

CMD
:: Set a temporary environment variable for the current session
set SA_ENV=value

:: Set a permanent environment variable for the current user (requires admin privileges)
setx SA_ENV value

:: Set a permanent environment variable for all users (requires admin privileges)
setx SA_ENV value /M

Windows PowerShell

To set an environment variable in PowerShell, you can use either Set-Item or New-ItemProperty cmdlets:

Powershell
# Set a temporary environment variable for the current session
$env:SA_ENV = "value"

# Set a permanent environment variable for the current user (requires admin privileges)
New-ItemProperty -Path "HKCU:\Environment" -Name "SA_ENV" -Value "value" -Force

# Set a permanent environment variable for all users (requires admin privileges)
New-ItemProperty -Path "HKLM:\System\CurrentControlSet\Control\Session Manager\Environment" -Name "SA_ENV" -Value "value" -PropertyType "String" -Force

macOS and Linux/Unix:

To set an environment variable in macOS or Linux using the terminal (bash), you can use the export command:

Bash
# Set a temporary environment variable for the current session
export SA_ENV=value

# Set a permanent environment variable for the current user
echo 'export SA_ENV=value' >> ~/.bashrc

# After updating the configuration file, apply the changes without restarting
source ~/.bashrc



Accessing the Configuration from Code

The GAIA API provides access to the Server configuration through the use of SERVER_CONFIG from the config module. By importing SERVER_CONFIG, developers can access all the server configuration properties as if they were regular objects. This allows for seamless interaction with and customization of the server configuration within your application.

To access the Server configuration using the GAIA API, follow these steps:

  1. Import the SERVER_CONFIG object from the config module in your Python code.

  2. Utilize SERVER_CONFIG to access the desired server configuration properties.


from config import SERVER_CONFIG

# Accessing the server configuration properties
host = SERVER_CONFIG.host
port = SERVER_CONFIG.port
auth_type = SERVER_CONFIG.security.authentication.type

# Use the server configuration properties in your application
print(f"Server Host: {host}")
print(f"Server Port: {port}")
print(f"Max Results: {auth_type}")


In the above example, the SERVER_CONFIG object is imported from the config module. The server configuration properties such as host, port, and auth_type are accessed directly from SERVER_CONFIG as regular object attributes. These properties can then be used within your application for further processing or customization.

Ensure that the config module is properly imported and available in your application environment to access the SERVER_CONFIG object.


  • No labels