Configuration

Appier configurations are simply a list of settings that are passed from outside the app, and made accessible to the application logic. They serve both as a single point of reference to variables that define the app's platform and behavior (eg: database server, logging level, etc.), and as a means to modify these when running the app in different environments (eg: having a different configuration for when it's running in a staging server than from when it's running in a production server).

Configuration can be specified through environment variables, local and/or environment file, with settings from the former overriding the latter.

Here's a local configuration file (appier.json in the application's root folder):

{
    "LEVEL" : "INFO"
}

That setting could also be configured through environment variables, which would override the very same setting defined in the local configuration file:

LEVEL=WARNING python hello.py

To retrieve configuration values from anywhere in the app do:

level = appier.conf("LEVEL")

You can also provide a default, so the app still works when that setting is missing:

level = appier.conf("LEVEL", "INFO")

Reference

The following are reserved configuration variables that modify Appier's behavior:

General

NameTypeDescription
SERVERstrThe server that will host the app: legacy, netius, waitress, tornado, cherrypi (default to legacy).
HOSTstrThe address of the server that serves the app (eg: 127.0.0.1 or 0.0.0.0).
PORTintThe port the server will listen at (eg: 8080).
SSLboolFlag indicating if SSL should be enabled.
KEY_FILEstrThe path to the SSL key file (mandatory if SSL is enabled).
CER_FILEstrThe path to the SSL certificate file (mandatory if SSL is enabled).
BACKLOGintThe number of connections to be hold waiting in server queue while pending accept operation.
FORCE_SSLboolFlag indicating if normal/plain requests (HTTP) should be rewritten to their secure/encrypted counterpart (HTTP).
FORCE_HOSTstrIf set and the host value (header) associated with the request does not match its value a rewrite operation in the request will be performed to ensure the host value.
HTTP_CLIENTstrThe client that will be used to perform HTTP requests: legacy, netius, requests (default: netius).
HTTP_REUSEboolIf the HTTP client connections should be re-used under a connection pool approach, or if instead a new connection should be create per request.
HTTP_TIMEOUTintThe number of seconds the HTTP client is going to wait until the connections is dropped.
BASE_URLstrThe address to prefix resolved URLs with, in order to turn them from relative to absolute URLs, when so specified (eg: emails links need to point to absolute URLs).
SECRETstrSecret key/string value to be used for cryptographic operations, should be based on PRNG generated value, if not defined a (properly generated) random value is used instead.
PARTSlistThe list of parts definitions (full class path) to be used for the dynamic loading of Appier Parts (eg: appier_extras.OpbeatPart).

Database

NameTypeDescription
ADAPTERstrThe (database) adapter that is going to be used for data storage (mongo, tiny, etc) (default: mongo).
MONGOHQ_URLstrURL pointing to a MongoDB server, written in the format the Heroku configuration expects to connect to MongoHQ (default: mongodb://localhost).
MONGOLAB_URIstrSame as MONGOHQ_URL.
MONGO_URLstrSame as MONGOHQ_URL.
MONGO_DBstrThe name of the database to be used as default in case it's not explicitly defined.
REDISTOGO_URLstrURL pointing to a redis server, should conform with the standard/expected URI format (default to redis://localhost).
REDIS_URLstrSame as REDISTOGO_URL.
TINY_PATHstrPath to the file that is going to be used as base for the TinyDB execution (should be JSON based).
TINY_STORAGEstrStorage engine to be used for persistence under TinyDB (json, memory, etc) (default: json).
SHOW_QUERIESboolDisplays extra debug information about the queries performed in the database.

Email

NameTypeDescription
SMTP_URLstrSimple URL based value that describes the SMTP configuration (eg: smtps://username:password@host.com:25).
SMTP_HOSTstrThe host where an SMTP server is running.
SMTP_PORTintThe port where an SMTP server is listening (default: 25).
SMTP_USERstrThe username used to authenticate with the SMTP server.
SMTP_PASSWORDstrThe password used to authenticate with the SMTP server.
SMTP_STARTTLSboolFlag used to tell the server that the client supports Transport Layer Security (default: True).
SMTP_HELO_HOSTstrThe address of the client connecting to the SMTP server, this will be sent as part of the HELO command send to the SMTP server.
EMAIL_LOCALEstrThe default locale to be used while sending emails, this may be overriden explicitly at runtime using the locale attribute.

Logging

NameTypeDescription
LEVELstrDefines the level of verbosity for the loggers: DEBUG, INFO, WARNING, ERROR, CRITICAL.
FILE_LOGboolEnables rotating file based logging (eg: /var/log/app_name.log, /var/log/app_name.err).
STREAM_LOGboolEnables the stdout stream based logging (default: True) .
MEMORY_LOGboolEnables the memory based JSON logging (default: True).
SYSLOG_HOSTstrThe hostname of the server running syslog for remote logging, if set also enables the remote syslog handler (default: None).
SYSLOG_PORTintThe port of the server running syslog for remote logging (default: 514 or 601).
SYSLOG_PROTOstrThe kind of protocol to be used for the syslog communication (default: udp).
LOGGINGlistDefines a sequence of logging handlers configuration to be loaded (eg: complex example project).
LOGGING_EXTRAboolIf extra values should be included as part of the logging format so that more debug information is available.
LOGGING_FORMATstrIf provided overrides the default logging format string for all handlers.

Cache

NameTypeDescription
CACHEstrDefines the cache manager to be used for general system operations (eg: file, memory, redis).
CACHE_PATHstrThe path to the directory where the file backed cache engine is going to store the cache files (default: None).

Preferences

NameTypeDescription
PREFERENCESstrDefines the preferences manager to be used (eg: file, memory, redis).
PREFERENCES_PATHstrPath to the file that is going to be used by the file preferences engine to store the preferences (using shelve).

Bus

NameTypeDescription
BUSstrDefines the bus manager to be used, the bus manager should allow the creation of a federated environment and its orchestration using an event driven approach (eg: memory, redis).
BUS_NAMEstrGlobal name used to create different diffusion scopes for different bus contexts (default: global).
BUS_SCOPEstrSame as BUS_NAME.

Session

NameTypeDescription
SESSIONstrDefines the session manager to be used (eg: file, memory, redis, client).
SESSION_FILE_PATHstrEnables changing of the default directory path for file session storage.

Scheduler

NameTypeDescription
SCHEDULER_TIMEOUTfloatDetermines the number of seconds between tick operation loops (default: 60.0).
SCHEDULER_DAEMONboolDefines if the scheduler thread should be run as a daemon (default: True).

Supervisor

NameTypeDescription
SUPERVISOR_INTERVALfloatThe number of seconds in between peer checking, this is also going to be used to control the timeout on the peer health check operation (default: 60.0).

Debug

NameTypeDescription
EXTENDED_PATHboolIf the file path URL should be set for every traceback line (default: True).
EXTENDED_GITboolIf the Git engine should be used for traceback debugging (default: False).

Other/Random

NameTypeDescription
MANAGERstrThe async manager to be used for the scheduling operations (async calls) (default: queue).
INSTANCEstrThe name of the concrete instance to be loaded, this value will affect default database naming, logging and other runtime loaded values (default: None).
PROFILEstrSame as INSTANCE.
NAMEstrThe visual name to be displayed on data associated with the instance, if not provided the default app class name is going to be used instead (default: None).
VERSIONstrVersion string on a triplet based structure, not recommended to override (default: None).
DESCRIPTIONstrSmall sentence with the description for the current application, if not provided the default internal strategy us going to be used to obtain the best possible description for the application (default: None).
OBSERVATIONSstrLong sentence to be used as the long description of the application, if not provided the default internal strategy is going to be used to obtain observations for .the application (default: None).
LOGO_URLstrThe URL of the main logo for the application (default: None).
LOGO_SQUARE_URLstrThe URL of the square version of the logo for the application (default: None).
LOGO_RASTER_URLstrIf provided ensures an alternative to LOGO_URL with a raster image (eg: PNG, JPEG, etc.) to be used in contexts where a vector image is not suitable .(default: None).
FAVICON_URLstrThe URL of the preferred favicon to be used by the application (default: None).
COPYRIGHTstrName of the company to which the copy rights of the application should be attributed (default: Hive Solutions).
COPYRIGHT_YEARstrThe year or range of year to be used in the copyright labels (default: 2008-2019).
COPYRIGHT_URLstrThe target URL for the copyright label (default: http://hive.pt).
LOCALEstrThe default locale value to be used for language, region and any special variant preferences.
APPIER_BASE_PATHstrOverride the default base path for the app (calculated as a relative directory to the main app file) (default: None).
HIGHLIGHTERstrThe name of the syntax highlighting library to be used in the main set of Appier pages, including the default HTML error page (eg: prism, highlight.js) (default: prism).
PIP_USERboolIf the appier controller pip_install operation should be done at an user level.