[[TOC]]
= Configuration Guidelines =
How to configure a new instance.

== File Permissions ==
{{{
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/languages/
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/languages/
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 ==
{{{
vim ~/.bashrc
alias w2p='cd ~web2py;python web2py.py -S eden -M'
alias pull="cd ~web2py/applications/eden;sed '/deployment_settings.base.migrate = False/ s/deployment_settings.base.migrate = False/deployment_settings.base.migrate = True/g' models/000_config.py >  models/000_config.py.new;mv models/000_config.py.new  models/000_config.py;bzr pull;chown web2py:web2py ~web2py/applications/eden/languages/*;/etc/init.d/apache2 force-reload;mv ~web2py/applications/eden/models/000_config.py.THIS ~web2py/applications/eden/models/000_config.py"
alias migrateoff="cd ~web2py/applications/eden;sed '/deployment_settings.base.migrate = True/ s/deployment_settings.base.migrate = True/deployment_settings.base.migrate = False/g' models/000_config.py >  models/000_config.py.new;mv models/000_config.py.new  models/000_config.py"
}}}

== Database Setup ==
Production system should use [wiki:InstallationGuidelinesMySQL 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'.

Old: Security policy is configured in {{{models/zzz.py}}}

== Configurable Options ==
These can be set via [http://127.0.0.1:8000/sahana/admin/setting/1/update]
 * Admin Name/Email/Tel
 * Debug: improve performance by deselecting this option.
 * Self-Registration: disable Self-Registration by deselecting this option.
 * Audit Read: Enable Auditing of all Read operations (Display)
 * Audit Write: Enable Auditing of all Write operations (Create/Update/Delete)

In time these will be configured by [wiki:BluePrintWebSetup 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 [wiki:BluePrintWebSetup 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 Modules 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
  * [wiki:HaitiGISToDo#LoadGISdata 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.

{{{
routes_logging = False
routes_onerror = [
        ('eden/401', '/eden/default/user/login'),
        ('eden/*', '/eden/errors/index'),
        ('*/*', '/eden/errors/index'),
    ]
}}}

== {{{favicon.ico}}} & {{{robots.txt}}} ==
These can be provided via 2 different means:
 * mod_rewrite
 * {{{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.[[BR]]
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 {{{000_config.py}}}: migrate = False
 * Use MySQL or PostgreSQL instead of SQLite
  * Create Indexes on commonly-accessed tables
 * set Empty=False in {{{models/zzz_1st_run.py}}} instead of doing a DAL hit
 * set modules to load from a hardcoded app name instead of substituting request.application in {{{models/00_db.py}}}

 * Use [http://developer.yahoo.com/yslow/ YSlow] Firefox plugin to analyse the site
 * Ensure images are optimised: http://tools.dynamicdrive.com/imageoptimizer/index.php
 * Compress !JavaScript: http://compressorrater.thruhere.net
 * Use [http://pypi.python.org/pypi/slimmer/ Slimmer] on HTML/CSS?
 * GZip static files in Apache: http://developer.yahoo.com/performance/rules.html#gzip
 * Set Expires on static files in Apache

 * Bytecode compile the application
 * 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 ([http://groups.google.com/group/web2py/browse_thread/thread/63543217b9a69955 Discussion])
 * Add Squid in front of Apache for caching?

----
InstallationGuidelines