~fabiocbalbuquerque/sahana-agasti/web-services

SAHANA AGASTI 2.0 MAYON 
Emergency Management Software

INSTALLATION INSTRUCTIONS

Updated: 2011-05-31

*** IMPORTANT NOTE: ***

These install instructions are currently tailored for systems running a LAMP
stack, specifically Ubuntu, Apache, MySQL, and PHP 5. The installation process
described in this document might work on other platforms, and with other web
servers or database engines, but it has not yet been thoroughly tested and is
not guaranteed. For questions or other support, please see the SUPPORT section
in the README file.


SYSTEM REQUIREMENTS
===================

Software
--------

The following software is required to run Sahana Agasti Mayon:

* Ubuntu 9.10 LTS or later (most current 10.04 LTS strongly recommended)
* Apache HTTP Server 2.2.14 or later (most current 2.2 preferred)
* MySQL 5.1.41 or later (most current 5.1 preferred)
* PHP 5.2.12 or later (most current 5.3 strongly recommended)
* APC (The Alternative PHP Cache) 3.1.8 or later

Hardware
--------

The following hardware resources are recommended to run Sahana Agasti Mayon:

* Intel Pentium or AMD Athlon CPU
* minimum of 50 MB available disk space
* minimum 512 MB RAM


SYSTEM CONFIGURATION
====================

After Sahana Agasti has been downloaded and extracted, you will first need to
configure your system before installing and using the application. These
instructions assume you have super user permissions on the target machine.

Apache
------

1. To set permissions to allow the web server appropriate access to the required
   directories, execute the following commands from the project root:

  sudo chgrp -R WEB_GROUP cache/ log/ config/ apps/*/config/ data/search/ \
      data/sql/ data/uploads/ data/downloads/ web/wiki/conf/ web/wiki/data/ \
      web/wiki/lib/plugins/dw2pdf/mpdf/tmp/
  chmod -cR g+wr config/ apps/*/config/ data/search/ data/sql/ data/uploads/ \
    data/downloads/ web/wiki/conf/ web/wiki/data/ web/wiki/lib/plugins/dw2pdf/mpdf/tmp/
  ./symfony project:permissions

  * NOTE: Replace WEB_GROUP with the group associated with the Apache user, e.g.
    www-data or apache.

2. Create a link to the web directory of the project from the server's web root,
   for example:

  $ sudo ln -s AG_ROOT/web WEB_ROOT/agasti

  * NOTE: Replace AG_ROOT with the full filesystem path to the Agasti root
    directory, and replace WEB_ROOT with the path to your default Apache
    configuration's document root.

3. If your version of Apache supports it, write a custom configuration file for
   the application; for example:

   Alias /agasti/sf AG_ROOT/lib/vendor/symfony/data/web/sf
    <Directory "/var/www/agasti">
      AllowOverride All
      Allow from All
    </Directory>

  To activate the site configuration, as well as mod_rewrite if it isn't
  already, you can then run the following commands:

  sudo mv agasti /etc/apache2/sites-available/
  sudo a2ensite agasti
  sudo a2enmod rewrite
  sudo /etc/init.d/apache2 restart

  * NOTES:

    - Again, replace AG_ROOT with the full file system path to the Agasti
      root directory.

    - Commands may vary slightly, depending upon your version of Apache.

    - You may instead prefer to set up an Apache Virtual Host, if you know how.

MySQL
-----

1. On the database server, create a schema for the project; for example:

   mysqladmin -uroot -p create AGASTI_DB

  * NOTE: Replace AGASTI_DB with the name you chose for the schema, e.g. agasti.

2. Create a dedicated database user for the application (using root is highly
   discouraged):

    GRANT ALL PRIVILEGES ON agasti_db.* TO '<agasti_db_username>'@'<db_hostname>'
     IDENTIFIED BY '<agasti_db_pass>';


  * NOTES:

    - Replace AGASTI_DB with the name you chose for the schema,
      AGASTI_DB_USERNAME with the username you chose, and AGASTI_DB_PASS with
      the password you chose.

    - For some versions of MySQL, you may need to FLUSH PRIVILEGES; before
      continuing.

3. Customize your MySQL options by adding the following either to a new .cnf
   file in your /etc/mysql/conf.d/ directory or to your /etc/mysql/my.cnf file:

    [mysqld]
    # sets default for charset=utf8 for client/connection
    character-set-server    = utf8
    collation-server        = utf8_general_ci

    # sets global sql_mode to enforce NOT NULL and other attribute constraints
    sql-mode=STRICT_ALL_TABLES

    [mysql]
    # sets default for charset=utf8 for server/database
    default-character-set   = utf8

  To activate the new options, restart MySQL:

  $ sudo restart mysql

  * NOTE: Depending on your platform and version of MySQL, you may need to use
    this command:

    $ sudo service mysql force-reload

    or this command:

    $ sudo /etc/init.d/mysql restart

PHP
---

Set PHP's memory and upload limits to the recommended minima by editing or
adding the following lines in /etc/php5/apache2/php.ini:

  memory_limit = 500M
  post_max_size = 64M
  upload_max_filesize = 64M

If there are any other major differences between your current php.ini and the
default recommended production settings, it is highly recommended that you reset
them via this command:

  $ sudo cp /usr/share/doc/php5-common/examples/php.ini-production \
      /etc/php5/apache2/php.ini

  * NOTES:

    - The other recommended settings would still need to be set after this copy.

    - Be sure to test that these changes don't negatively affect other PHP
      applications you might be running.

Finally, be sure to also specify your timezone in php.ini; for example:

  date.timezone = "America/New_York"

Replace "America/New_York" with your own from the List of Supported Timezones,
linked at http://php.net/date.timezone .

APC
---

If you haven't installed APC, this is currently the recommended command to get
the most recent stable build:

  $ sudo apt-get install libpcre3 libpcre3-dev
  $ sudo pecl install apc

The following lists our recommended settings for APC configuration, located in
/etc/php5/conf.d/apc.ini:

  ; Enable APC extension module
  extension=apc.so

  ; Options for the APC module
  apc.enabled = 1
  apc.shm_segments = 1
  apc.optimization = 0
  apc.shm_size = 256M
  apc.ttl = 7200
  apc.user_ttl = 7200
  apc.num_files_hint = 1500
  apc.mmap_file_mask = /tmp/apc.XXXXXX
  apc.enable_cli = 1
  apc.cache_by_default = 1
  apc.include_once_override = 1
  apc.slam_defense = 1

It is recommended to change these only if you encounter an error and are
comfortable with the settings do; see http://php.net/apc.setup for more
information. When you are finished, restart Apache:

  $ sudo /etc/init.d/apache2 restart


APPLICATION INSTALLATION
========================

After you have configured your system, navigate to the install page for your
Agasti instance, e.g.:

  http://localhost/agasti/install.php

Follow the instructions on each screen, making modifications to your system in
response to any reported misconfigurations and entering appropriate information
when prompted.

After reviewing the installation configuration summary, the next step may take a
few minutes before the installer reports that is has completed and you can click
the "Finish" button.

At this point you will need to set the login credentials for the superuser by
editing the AG_ROOT/config/config.yml file (as a superuser) and replacing the
null super_user and super_pass values with something valid and secure, e.g.:

  super_user: 'somesecureusername'
  super_pass: '$ome.$ecure.pa$$w0rd!'

You should now be able sign in with those credentials and use the application.

To port these credentials to the wiki, run the script:

  sudo -u [WEB_USER] php [AG_ROOT]/apps/frontend/lib/util/wiki-auth-setup.php

Finally, generate the wiki indexes by running the following command:

  sudo -u [WEB_USER] [AG_ROOT]/web/wiki/bin/indexer.php -c

  * NOTES:

    - Replace WEB_USER with the user associated with the Apache, e.g.
      www-data or apache.


ERRORS AND TROUBLESHOOTING
==========================

- Blank page after clicking "Install", or "500" error page:

  The file permissions or database permissions are possibly misconfigured.
  Ensure the web server has proper access to the appropriate files and
  directories and check your web server error log. Also, ensure the proper
  version of PHP is installed; please see the SYSTEM REQUIREMENTS section.

- 404 error page:

  Verify that symbolic links are being followed and that your web server is
  pointing to the expected directory for the application.

- Installation instructions are followed properly and all settings configured
  correctly, but still unable to log into the application with proper
  credentials:

  Clear the Symfony cache with this command, executed from your AG_ROOT:

  $ ./symfony cc

  and try again.

- If the database has been deleted and you are unable to log in, even with the superadmin credentials enable super admin by editing the /apps/frontend/config/app.yml file by adding the following lines after the first line (which should read 'all:')

  sf_guard_plugin:
    check_password_callable:
      - agSudoAuth
      - authenticate
  sf_guard_plugin_signin_form: agSudoSigninForm

It is important that pre-line spacing is maintained in the copy and paste of the lines.

- I have another error, or my issue still isn't resolved:

  Please see the SUPPORT section in the README file for information on how to
  contact the developer community.


Thank you for using Sahana Agasti!
                                     The Sahana Software Foundation
                                     http://www.sahanafoundation.org/