Configuration Guidelines

How to configure a new instance.

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:

• Edit models/000_config.py

Security

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

deployment_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

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

• Admin Name/Email/Tel

In time these will be configured by Web Setup.

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

deployment_settings.auth.registration_requires_verification = False
deployment_settings.auth.registration_requires_approval = False
deployment_settings.base.public_url = "http://127.0.0.1:8000"
deployment_settings.base.migrate = True
deployment_settings.mail.server = "127.0.0.1:25"
deployment_settings.mail.sender = "sahana@your.org"
deployment_settings.mail.approver = "useradmin@your.org"
deployment_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.

Disable unnecessary modules, which is currently done in models/000_config.py

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

• edit file models/01_modules.py
• section: s3.menu_modules

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

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:

• ​http://localhost:8000/sahana/gis/map_service_catalogue

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

API Keys for Google, Yahoo & MultiMap layers:

• ​http://localhost:8000/sahana/gis/apikey

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

• ABQIAAAAgB-1pyZu7pKAZrMGv3nksRR1-chREdZE62d-MGawPNPOGidOJBQQCwHsElsSGbD5VMpNj7DBMNxjTg

Import Admin Boundaries:

• The locations hierarchy should be populated with L0->L3 data, which are often available in the form of shapefiles
  • Haiti example
  • USA L1-L2: ​http://www2.census.gov/cgi-bin/shapefiles/national-files

Enable Scheduled Tasks

Edit cron/crontab to enable sending of emails & SMS:

# Send outgoing emails every 5 minutes
*/5   *       *       *       *       root *msg/process_email_via_api
# Send outgoing SMS every 5 minutes
*/5   *       *       *       *       root *msg/process_sms_via_api

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:

• select using Admin Panel:
  • ​http://127.0.0.1:8000/eden/admin/theme

Logo:

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

Footer:

• amend views/footer.html

DeveloperGuidelinesThemes

Internet Hosting

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

• The CDN may have faster/closer servers to the client
• Increases the number of files being downloaded simultaneously, since pulled from different hostnames: ​http://www.websiteoptimization.com/speed/tweak/parallel/

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:

  deployment_settings.base.migrate = False
  deployment_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

• Use ​YSlow Firefox plugin to analyse the site
• Ensure images are optimised: ​http://tools.dynamicdrive.com/imageoptimizer/index.php
• DeveloperGuidelinesOptimisation#JavaScript
• Compress JavaScript: ​http://compressorrater.thruhere.net
• Use ​Slimmer on HTML/CSS?
• GZip static files in Apache: ​http://developer.yahoo.com/performance/rules.html#gzip
• Set Expires on static files in Apache

• Enable caching
  • return response.render('customview.html', data=data): ​http://groups.google.com/group/web2py/msg/39210d40d8a729c0
• ​http://groups.google.co.uk/group/web2py/browse_thread/thread/218bb58c96883578
• Clustering with Pound: ​http://www.web2pyslices.com/main/slices/take_slice/33 (​Discussion)
• Add Squid in front of Apache for caching?
• HAProxy, etc: ​http://www.slideshare.net/zeeg/djangocon-2010-scaling-disqus

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:
   • Apache
   • Cherokee
5. Remember to maintain this page if you make changes to the main page!

---

InstallationGuidelines