Sahana Eden

Configuration

Sahana Eden is a highly configurable system that can be adapted to many different needs and situations. If you've taken the time planning your project and have answered the questions posed in the "Planning a Deployment" section, you are now simply looking for where to enter the answers.

Configuration through the web interface

At the moment only some settings, like SMS, email inbox and Twitter, are editable through the Web UI. Future plans are to add more configuration settings through the Web UI but for now most configuration options require editing text files.

Configuration through text files

Many configuration options can be changed by editing models/000_config.py. This consists of sections of Python code where settings for a particular component of the system can be changed. Most of the changes take effect immediately after saving the file. For a production environment then the system would need to be recompiled.

models/000_config.py has to be edited before using Sahana Eden. Once you have edited models/000_config.py, change the FINISHED_EDITING_CONFIG_FILE variable  to True.

There are comments placed next to the options which are generally self-explanatory in nature. Users must not change the variables (or their names), they just need to change their values to configure the instance.

The following sections of models/000_config.py are explained in more detail:

Database Settings

It is recommend that production systems use PostgreSQL or MySQL rather than the default SQLite. For these databases it is more secure to provide the application with a database account with minimal privileges.

This section of the models/000_config.py file can be used to configure settings like:

  • Database Host: The server where your database is hosted
  • Database Name: The name of the database being used
  • Username: The username that has been assigned to the user for use with Eden
  • Password: Password assigned to the user
  • Port: Port at which the database service is available. Set to None to use the default setting

Authentication Settings

Administrators can use these settings to implement security policies and to make sure that there is no unauthorized access or data manipulation in the system. These settings are related to creating the first user account of the system and determining how users register and access the system.

Base Settings

Users can configure the system name, the public URL of the system and data pre-population in this section of models/000_config.py.

One of the most important system settings would be the selection of the template as this can completely alter how Sahana operates as well as it's look & feel. A list of available templates is in the folder private/templates. Any template setting can be over-ridden within 000_config.py for further fine-tuning as-required.

One of these settings is database pre-population. Users can determine if the database will be pre-populated with sample data or not.

Changing the database migration setting to False in production will lead to a performance gain. Migration tries to alter the SQL database schema to match that expected in the code. This works very well for simple cases, but may result in loss of existing data for complex cases, so should be applied with care to Production servers.

Web2Py supports automatic migration, but having this enabled all the time does lead to reduced performance, so enable migration only when necessary.

Mail Settings

Sahana Eden can be configured to use a email service for messaging. This section can help you to set up things like the outbound email server and sender address. Note: Until the Sender address is specified, the system will be unable to send emails!

Front Page Settings

Sahana Eden has a dynamic front page with a capability to display RSS or Twitter feeds. You can change certain aspects of the landing page of the application in the frontpage settings section of the code.

Settings in this section can be used to change which RSS and Twitter feeds are subscribed to and displayed on the front page of the application.

Module-specific Settings

Some settings for the Request Management, Inventory Management and Human Resource Management modules can be accessed here. These settings would generally be very specific to the needs of a certain deployment.

Enabling/Disabling Modules

Sahana Eden supports a range of modules that can be enabled or disabled to support different deployments. The default template (private/templates/default/) has all the main modules enabled as standard (you may notice that some other modules are disabled as standard; these tend to be under development or experimental).

Disabling a module has the effect of removing it from the main menu of the application. All modules can be disabled except core modules: Home (default), Administration (admin), Map (gis), Person Registry (pr) and Organization Registry (org).

There are three ways to disable modules. The most direct way to do this is to comment out the revelevant lines of code in the configuration file of the default template: private/templates/default/config.py. To turn a line into a comment, simply make sure it begins with a # symbol.

For instance, consider the Shelter Registry (named "cr"). The following code section in private/templates/default/config.py applies to the Shelter Registry: 

("cr",
Storage(
    name_nice = T("Shelters"),
    #description = "Tracks the location, capacity and breakdown of victims in Shelters",
    restricted = False,
    module_type = 10,
    )),

To disable this module, just make sure that each line in this section starts with a hash (#) symbol: 

#("cr",
#Storage(
#    name_nice = T("Shelters"),
#    #description = "Tracks the location, capacity and breakdown of victims in Shelters",
#    restricted = False,
#    module_type = 10,
#    )),

The module is now disabled and will no longer show up in the application menu.

The drawback of this approach, however, is that the default template will be updated whenever you update your code, and any changes you have made risk being lost. For a long-term solution, it is recommended that you create a new template for your implementation.

Most implementations of Sahana Eden involve the creation of a template folder specific for that project. This will be placed within private/templates, as an alternative to the default. The settings.base.template = “default” line within models/000_config.py will then be changed to reflect the name of the new template folder. Eden will initially look within this folder for a config.py file, and if one is present, it will use the module list defined there rather than the one within the default template. To disable unwanted functionality, create a custom version of config.py within your template folder, with unwanted modules commented out as described above.

There is a third option for disabling modules that can be useful in some cases. When testing, for example, or when demonstrating a sub-set of functionality, for example, it may be useful to disable modules without altering the templates. For this, models/000_config.py can be used, and a section of that file is provided for adding in overrides to the template. Add to this section a new line of code for each unwanted module: 

settings.modules.pop("unwanted-module-name", None)

This will remove the module from the list that was created by the template. For example: 

settings.modules.pop("cr", None)

While the above line is present, the Shelter Registry will be disabled, just like in the previous example. Because updates to the code do not touch models/000_config.py, this change will also be safe from unwanted modification.

For more information on templates, see the Customisation section of this book.

Updates to 000_config.py

So that your configuration settings are not changed when you update the code for your implementation, your local copy of models/000_config.py is not updated with the rest of the code. Very occasionally, however, updates to 000_config.py are necessary. If you do experience problems following an update, it is worth checking your copy of 000_config.py in the models folder with the current version. The current version can be found on your system in private/templates/000_config.py.

Further information on configuring Sahana Eden can also be found at http://eden.sahanafoundation.org/wiki/ConfigurationGuidelines