wiki:ConfigurationGuidelines

Configuration Guidelines

How to configure a new instance.

Changing the Template

To change the instance's Sahana template:

# Initially <OLD TEMPLATE> = default
# You can also edit the config file directly: /home/prod/eden/models/000_config.py
sed-i '|template = "<OLD TEMPLATE>"|template = "<NEW TEMPLATE>"|' /home/prod/eden/models/000_config.py
compile

# This will delete all current data and pre-populate from the new template
clean

Switch to an alternate GitHub repo

If you wish to update your site from an alternate github repo this can be done using:

cd ~web2py/applications/eden
git remote set-url origin https://github.com/USERNAME/eden.git
pull

(replace 'USERNAME' & 'eden' as-required)

'pull' assumes that the appropriate management script is installed, otherwise can use the individual commands contained therein: git pull, etc

File Permissions

Note: As of January 2012, BZR/Launchpad info for eden is deprecated. Please visit the GitHub page. Thanks.

For Linux installations only.

chown web2py ~web2py/applications/admin/cron
chown web2py ~web2py/applications/admin/cron/crontab
chown web2py ~web2py/applications/admin/cache/
chown web2py ~web2py/applications/admin/databases/
chown web2py ~web2py/applications/admin/errors/
chown web2py ~web2py/applications/admin/sessions/
chown web2py ~web2py/applications/admin/uploads/
cd web2py/applications
bzr branch lp:sahana-eden eden
chown web2py eden/cron
chown web2py eden/cache/
chown web2py eden/databases/
chown web2py eden/errors/
chown web2py eden/sessions/
chown web2py eden/static/img/markers
chown web2py eden/static/scripts/tools
chown web2py eden/static/styles/S3/sahana.css
chown web2py eden/static/styles/S3/sahana.min.css
chown web2py eden/uploads/
mkdir eden/uploads/gis_cache
mkdir eden/uploads/images
mkdir eden/uploads/tracks
chown web2py eden/uploads/gis_cache
chown web2py eden/uploads/images
chown web2py eden/uploads/tracks

Useful Aliases

For Linux installations only.

vim ~/.bashrc
alias w2p='cd ~web2py;sudo -H -u web2py python web2py.py -S eden -M'
alias compile='cd ~web2py;python web2py.py -S eden -R applications/eden/static/scripts/tools/compile.py'
alias pull="cd ~web2py/applications/eden;sed -i 's/deployment_settings.base.migrate = False/deployment_settings.base.migrate = True/g' models/000_config.py;bzr pull;rm -rf compiled;cd ~web2py;sudo -H -u web2py python web2py.py -S eden -M -R applications/eden/static/scripts/tools/noop.py;/etc/init.d/apache2 force-reload"
alias migrateoff="sed -i 's/deployment_settings.base.migrate = True/deployment_settings.base.migrate = False/g' ~web2py/applications/eden/models/000_config.py"

Easier to maintain as scripts (see attached)

Database Setup

Production system should use MySQL or PostgreSQL:

  • Edit models/000_config.py

Security

Before the 1st login, edit models/000_config.py:

settings.auth.hmac_key = "akeytochange"

Roles

By default the 1st user to register will gain the Administrator role.

All other users have just the 'Authenticated' level of access, which by default allows full Read/Update/Delete access to all records.

If allowing public self-registration, then you probably want to enable 'Editor' secturiy policy (Administration menu | Settings) which means that the general public can add records (& modify their own) but cannot modify other records.

To add roles to users, go to the Administration menu & within User Management choose 'Membership'.

Security policy is initially defined in models/zzz_1st_roles.py but then subsequently managed via the database.

Configurable Options

Basic Options

These can be set via http://127.0.0.1:8000/sahana/admin/setting/1/update

In time these will be configured by Web Setup.

Some options are currently only configurable via editing models/000_config.py:

settings.auth.registration_requires_verification = False
settings.auth.registration_requires_approval = False
settings.base.public_url = "http://127.0.0.1:8000"
settings.base.migrate = True
settings.mail.server = "127.0.0.1:25"
settings.mail.sender = "sahana@your.org"
settings.mail.approver = "useradmin@your.org"
settings.L10n.utc_offset = "UTC +0000"

We would like to expose these to a Web Setup, although it's low priority as these are mostly installation-time decisions.

Modules and Menu

Enabling & Disabling unnecessary modules is done in either:

Active modules are stored in settings.modules, which is an instance of OrderedDict. The key of each item in this OrderedDict is the name of the module (a string), and each value is an instance of Storage. To disable a module, either comment out the relevant lines of config.py in the template, where the list is populated, or else use the delete it in models/000_config.py to remove the relevant item from settings.modules.

Can also reorganise the menus completely to better display those relevant to the instance:

Table Fields

If you wish to hide some fields which you don't want to confuse your system, then you can do something like this models/zzz_local.py instead of amending the main model (this means that future merges from trunk won't clobber your changes):

# Hide unnecessary fields
tablename = 'pr_person'
table = db[table]
table.pr_pe_label.readable = False
table.pr_pe_label.writable = False
table.local_name.readable = False
table.local_name.writable = False
table.opt_pr_gender.readable = False
table.opt_pr_gender.writable = False
table.opt_pr_age_group.readable = False
table.opt_pr_age_group.writable = False
table.email.readable = False
table.email.writable = False
table.mobile_phone.readable = False
table.mobile_phone.writable = False
table.date_of_birth.readable = False
table.date_of_birth.writable = False
table.opt_pr_nationality.readable = False
table.opt_pr_nationality.writable = False
table.opt_pr_country.readable = False
table.opt_pr_country.writable = False
table.opt_pr_religion.readable = False
table.opt_pr_religion.writable = False
table.opt_pr_marital_status.readable = False
table.opt_pr_marital_status.writable = False
table.occupation.readable = False
table.occupation.writable = False

Registration Message Options

The welcome message and other messages relating to registration and logging in are in current.auth.messages which can be configured in a customise_auth_user_resource() function in your template's config.py file.

To see the messages that can be changed, look for the messages.* lines in the AuthS3.__init__ function in modules/s3/s3aaa.py. These also show examples of using format elements like %(system_name)s to insert the system name, url, user name, and link to the user's profile. Use the same format elements in your messages to have those inserted.

Example:

def customise_auth_user_resource(r, resource):
    messages = current.auth.messages
    messages.welcome_email_subject = "Welcome to %(system_name)s!"
    messages.welcome_email = \
"""Welcome to %(system_name)s, %(first_name) %(last_name)!
* You can start using %(system_name)s at: %(url)s
* To edit your profile go to: %(url)s%(profile)s
Thank you for registering!"""

settings.customise_auth_user_resource = customise_auth_user_resource

These messages do not need T( ) around them. If a translation is required they need adding to the languages/xx.py file.

As-usual, for a site with multiple languages, it is suggested to include the original message in English to serve as the key in the translation files, and to include the format elements (for system name, etc.) in the message, so that the translator can rearrange them as needed.

Mapping Options

http://localhost:8000/sahana/gis/config/update/1

Default Map Portal:

  • Lat
  • Lon
  • Zoom

Bounds of relevant area:

  • Min Lon
  • Max Lat
  • Min Lon
  • Max Lat

Selecting Base Layers:

Test out whether OpenStreetMap, Google, Yahoo or Bing have the best road maps & Satellite imagery

API Keys for Google, Yahoo & MultiMap layers:

For *.sahanafoundation.org, we can use this Google Key:

  • ABQIAAAAgB-1pyZu7pKAZrMGv3nksRR1-chREdZE62d-MGawPNPOGidOJBQQCwHsElsSGbD5VMpNj7DBMNxjTg

Import Admin Boundaries:

Ticket Viewer

Add the following to routes.py of your web2py installation for pretty error pages & the ability to view Tickets.

  • copy from routes.example.py, if one doesn't yet exist.
#!/usr/bin/python
default_application = 'eden'
default_controller = 'default'
default_function = 'index'
routes_onerror = [
        ('eden/400', '!'),
        ('eden/401', '!'),
        ('eden/*', '/eden/errors/index'),
        ('*/*', '/eden/errors/index'),
    ]

favicon.ico & robots.txt

These can be provided via 2 different means:

  • mod_rewrite
    DocumentRoot /home/web2py/applications
    RewriteEngine On
    RewriteRule .*favicon.*\.ico$ /eden/static/favicon.ico [L]
    RewriteRule .*robots\.txt$ /eden/static/robots.txt [L]
    RewriteRule ^/$ /eden/ [R]
    
  • web2py/routes.py: copy routes.example.py & edit

Themes

Ensure these files are writable by the webserver:

chown www-data /path/to/web2py/applications/eden/static/scripts/tools
chown www-data /path/to/web2py/applications/eden/static/styles/S3/sahana.css
chown www-data /path/to/web2py/applications/eden/static/styles/S3/sahana.min.css

Colour scheme:

Logo:

  • copy new logo to static/img
  • point to this using Admin Panel

Footer:

  • amend views/footer.html

DeveloperGuidelines/Themes

Internet Hosting

Can switch to having users download files from CDNs instead of your server.
This can improve performance in 2 ways:

jQuery from Google by uncommenting the line in views/sahana_scripts_min.html

ext-all.js & ext-all.css from Cachefly by uncommenting the lines in views/gis/gis_scripts_min.html & views/gis/ol_js_loaders.html

Performance Optimisation

  • Disable DB migrations in models/000_config.py:
    settings.base.migrate = False
    settings.base.prepopulate = False
    
  • Use a CDN for public sites models/000_config.py:
    deployment_settings.base.cdn = True
    
  • Remove comments & unused code from views/layout.html & views/s3_include_min.html
  • Set modules to load from a hardcoded app name instead of substituting request.application in models/00_db.py
  • Bytecode compile the application:
    cd /home/web2py
    python web2py.py -S eden -M -R applications/eden/static/scripts/tools/compile.py
    
  • Use MySQL or PostgreSQL instead of SQLite
    • Create Indexes on commonly-accessed tables

Static Home Page

In order to improve performance & scalability, you may wish to set a page (usually the homepage) as static. To do this:

  1. Visit the page in a browser & Save to /static/index.html
  2. Edit the page to remove anything unnecessary (e.g. Ext)
  3. Adjust paths to ../ instead of /eden/ if you wish the app to remain portable
    • include the Language selector dropdown, if-used
  4. Configure the Web server to redirect to this static page for unregistered users:
  5. Remember to maintain this page if you make changes to the main page!

InstallationGuidelines

Last modified 2 years ago Last modified on 12/13/18 10:20:50

Attachments (5)

Download all attachments as: .zip

Note: See TracWiki for help on using the wiki.