[[TOC]] = Configuration Guidelines = How to configure a new instance. == Changing the Template == To change the instance's Sahana [wiki:DeveloperGuidelines/Templates template]: {{{ # Initially = default # You can also edit the config file directly: /home/prod/eden/models/000_config.py sed-i '|template = ""|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 git://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.'''[[BR]] 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 [wiki:InstallationGuidelines/MySQL MySQL or PostgreSQL]: * 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 [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 either done in {{{models/000_config.py}}} or in the template's {{{config.py}}} file. 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 pop method in {{{models/000_config.py}}} to remove the relevant item from settings.modules. 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 * [wiki:HaitiGISToDo#LoadGISdata Haiti example] * USA L1-L2: http://www2.census.gov/cgi-bin/shapefiles/national-files == 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}}} DeveloperGuidelines/Themes == 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 {{{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 [http://developer.yahoo.com/yslow/ 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 [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 * 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? * 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 1. Edit the page to remove anything unnecessary (e.g. Ext) 1. Adjust paths to ../ instead of /eden/ if you wish the app to remain portable * include the Language selector dropdown, if-used 1. Configure the Web server to redirect to this static page for unregistered users: * [wiki:InstallationGuidelinesApacheModWSGI#Statichomepage Apache] * [InstallationGuidelinesCherokee#Statichomepage Cherokee] 1. Remember to maintain this page if you make changes to the main page! ---- InstallationGuidelines