Core Configuration
Overview
Riberry's core configuration is declared using the toml configuration format.
A sample configuration file can be viewed here.
Dynamic parameters
Having one centralised configuration file can be difficult to manage when it mixes sensitive data and common system parameters together. If secrets were stored in plaintext in a configuration file, anyone with access to view the common system parameters will have access to view sensitive pieces of information.
To address this, we've allowed some parameters to be declared dynamically. A dynamic parameter can be defined in three ways:
[section]
envvar = "ENVIRONMENT_VARIABLE"
path = "/path/to/file/containing/secret"
value = "secret_value"
It's not uncommon to define secrets in environment variables (Jenkins, Travis CI) and in-memory files (Docker secrets), which the above caters for.
1. Background configuration
Celery
This section contains the configuration for Riberry's Celery background workers. All keys defined here will be passed directly to Celery.
[celery]
result_backend = 'redis://'
broker_url = 'redis://'
timezone = 'UTC'
Celery's configuration user-guide can be view here.
Events Processor (Celery Worker)
[background.events]
limit = 1000
interval = 2
background.events.limit (integer)
Specifies the maximum amounts of events to process at once. Events include notifications, stream information and artifact data.
Applications which frequently generate large artifacts will consume high amounts of RAM if the limit is not correctly capped, so be sure to tweak this parameter to your required use case.
background.events.interval (integer)
This is the time (in seconds) that events will be processed.
Job Scheduler (Celery Worker)
[background.schedules]
interval = 5
background.schedules.interval (integer)
This is the time (in seconds) that all job schedules will be processed.
The lower the value the greater the accuracy in triggering job schedules. The worst case scenario is that a job will be triggered interval seconds after it was originally scheduled to execute.
2. Database Configuration
This section breaks down the database-related configuration. The ORM internally used by Riberry is SQLAlchemy.
Connection
[database.connection]
# Dynamic parameter which defines the database URL
envvar = "ENVIRONMENT_VARIABLE"
path = "/file/with/value"
value = "sqlite://..."
echo = false
database.connection.(path | envvar | value) (dynamic)
Dynamic parameter defining the database's connection URL. Accepts any format supported by SQLAlchemy. Documentation on the formats can be found here.
Tested databases include sqlite, postgresql and Oracle.
database.connection.echo (boolean)
Toggles the echo behaviour on the underlying SQLAlchemy database engine. If enabled, SQLAlchemy will output additional debug messages **(documentation).
Arguments
[database.arguments]
timeout = 60 # relevant to sqlite, passed directly to sqlite3's connect() method
Passes the provided arguments to the underlying driver's DBAPI connect() method (documentation).
3. Notifications
This section explains the configurable notification parameters present in Riberry.
[notification.email]
enabled = false
smtpServer = "..."
sender = "noreply@example.com"
notification.email.enabled (boolean)
Enables/disables email notification.
notification.email.smtpServer (boolean)
Sets the SMTP server to connect to.
notification.email.sender (boolean)
The email address to use as the sender in the email notification.
4. Authentication
Details all the authentication related parameters that Riberry provides, as well as how to extend the authentication mechanism with external authentication providers.
Providers
[authentication.providers]
supported = ["default", "ldap"]
default = "default"
authentication.providers.supported (boolean)
Specifies the supported authentication providers. default is the only built-in authentication provider, though additional providers can be installed via plugins.
authentication.providers.default (boolean)
The default authentication provider.
This provider will be used to authenticate when a user is trying to authenticate with a username which does not exist in Riberry. Otherwise the provider which is assigned to that username will instead.
Token
[authentication.token]
provider = "jwt"
envvar = "RIBERRY_AUTHENTICATION_SECRET"
path = "/path/containing/token"
value = "plaintext_token"
authentication.token.(path | envvar | value) (dynamic)
Dynamic parameter containing a secret used by the token provider to generate a token. The format of the secret is dependent on the provider.
authentication.token.provider (string)
Defines which authentication token provider to use. The token being generated will be used to generate session tokens which verify the user's identity.
jwt provider
JWTs (or JSON Web Tokens) are the only supported token providers at this time.
The token provided via authentication.token.(path | envvar | value) is used to sign and verify session tokens. The longer the string, the greater the security. The string should be randomly generated and securely stored.
You can generate a secure secret using Python 3.6's secret module:
>>> import secrets
>>> secrets.token_hex(32)
'b5620a5260...'
LDAP (plugin)
This section is under construction and is incomplete