Configuring Nucleon Applications

A Nucleon app’s configuration is loaded from a file named app.cfg, which must reside in the same directory as the application’s The configuration file is in standard Python ConfigParser format.

Settings are loaded from sections within the configuration file named by environment - different environments (demo, staging, qa, production, etc.) may well have different connection settings for databases, queues, services and so on. Each application is configured at start time to use settings for a particular environment.

Selecting an environment

The default environment is called ‘default’ and so is loaded from the configuration file section named [default].

However, when running tests, settings are loaded from the test environment. This switch is currently enacted by calling nucleon.tests.get_test_app().

Configuration API

In an application, settings for the current environment can be retrieved as properties of a global settings object.


A global settings object that reflects the current environment.

Config variables are available as properties of this object.


The name of the currently active environment.


Change to a different environment.

This method will raise ConfigurationError if any settings have been read. The alternative could allow the application to become partially configured for multiple different environments at the same time, and pose a risk of accidental data loss.

For example, reading the currently configured database is as simple as:

from nucleon.config import settings
print settings.database

Database access credentials

Databases can be configured for each environment by using the following syntax:

database = postgres://username:password@host:5432/databasename

‘database’ is not a special name - just the default. Specific database connections can be requested by passing the name of their configuration setting when retrieving a connection pool from the app with nucleon.framework.Application.get_database(). Thus a Nucleon app can easily use connections to multiple databases (albeit with a risk of deadlocks if greenlets require exclusive use of connections on multiple databases).

Nucleon can manage the set up of database tables and inserting initial data. This is achieved using the commandline tools - see Nucleon Management Commands for full details.