Developer's Live Disc

To help new developers and those unfamiliar with system administration tasks, a few members of the Agasti team put together a live disc that comes pre-configured with all the software and server configurations a developer should need in order to become a meaningful contributor to the project. This live disc can be burned to a DVD (hopefully, we'll one day get it shrunk to a CD-size), or installed in a virtual machine such as vmware workstation or KVM.

To get a hold of this great tool, visit our generous host at http://ftp.osuosl.org/pub/sahana/agasti/ where you can find the mayon-ide.iso file. Simply click the link to start your download.

To ensure that your download was not corrupted during transfer or by malicious software we recommend running an md5 checksum of the downloaded ISO and comparing it against the IDE checksum posted with the iso.

For those who wish to run this disc in a virtualized state, we applaud you! That's how we built and maintained this image! Unfortunately, virtualization as a solution is very dependent on both your hardware and your virtualization software (like VmWare, KVM, or VirtualBox). That makes it very difficult for us to troubleshoot because we're not likely to know your setup. Luckily, a lot of people have spent their time writing guides on how to start up a virtual machine. We recommend you start with the Ubuntu KVM guide and see if that works for you.

All you need to know is that the mayon-ide.iso you downloaded should be the virtual cdrom image for your installation.

Notable software found on this Live Disc include:

This distribution is based on Lubuntu, a lightweight LXDE derivative of Ubuntu, and comes with a number of default system software not mentioned here. For more information visit http://lubuntu.net/.

The first thing you do when you start the VM should be to read the ReadMe.txt (found on your desktop). After you've done so, please take a moment to set new credentials to protect you and your new system, from abuse.

At the bottom of this page, you'll find a copy of the ReadMe.txt taken on 2011-03-21. Please keep in mind that the ReadMe.txt and these directions are not synchronously maintained and may diverge. This is presented merely as an example.

Please read the ReadMe.txt found with your new install to complete your installation!

After installation is complete (and you've pulled from the source), you should feel free to fire up Netbeans and Firefox and dev-away.

For the moment, this Live Disc is offered as a service to the Agasti community by a few members who are committed to helping ease the transition for new developers. While we are happy to offer it, this Live Disc is not officially supported as part of the Agasti project but rather, supported independently by those who initially created it. As-such, it will be updated and maintained as time allows and those with issues are encouraged to either Ask a Question or Submit a Bug Report on Launchpad.

Sample ReadMe.txt

SAHANA AGASTI 2.0 MAYON
Emergency Management Software
 
Hello and Weclome to the Sahana Agasti Mayon developer's VM. This machine
image has been designed to help developers become effective contributors
without having to worry about the complexities of server administration or
instantiation of project tools.
 
While this VM does reduce the effort to getting started, there are still
a few steps remaining. Please follow the remaining instructions in this
file to begin your adventure in the world of Agasti development.
 
 
CREDENTIALS MANAGEMENT
======================
To make things simple to use, most of this images credentials have already
been established. The current settings are found below:
 
  System Username:    <in the real file>
  System Password:    <in the real file>
 
  DB Root Passowrd:   <in the real file>
  Agasti DB Name:     <in the real file>
  Agasti DB Username: <in the real file>
  Agasti DB Password: <in the real file>
 
You are STRONGLY ENCOURAGED to change these credentials at your earliest
opportunity.
 
To change your system password, execute the following in the command line:
  $ passwd
 
To change your MySQL root password execute the following, replacing
$NEWPASS with your new password:
  $ mysqladmin -u root -p'mayon' password $NEWPASS
 
To change your agasti db password execute the following, replacing
$NEWPASS with your new password:
  $ mysql -u root -p -e "UPDATE user SET password=PASSWORD('mayon') WHERE user='agasti'; flush privileges ;" mysql
 
 
TELL US WHO YOU ARE
===================
The Agasti Mayon codebase is managed using the bazaar version control system.
Bazaar is very powerful, but it can be confusing to the uninitiated. It's
recommended you start using bzr by introducing yourself to it.
 
Set your whoami, replacing $FIRSTNAME, $LASTNAME, and $EMAIL, respectively:
  $ bzr whoami "$FIRSTNAME $LASTNAME <$EMAIL>"
 
While you're at it, why don't you create an account on Launchpad? Simply
head to http://help.launchpad.net/YourAccount/NewAccount and follow all
of their instructions.
 
Be sure to get as far as setting and importing your ssh keys!
 
 
UPDATE YOUR BRANCH
===================
Because it's likely that the codebase has diverged since this image was last
created, you should start by updating your branch.
 
First navigate to the project directory:
  $ cd /home/agastidev/Desktop/sahana-agasti-mayon
 
Then execute a pull to get the latest updates from trunk.
  $ bzr pull lp:sahana-agasti/mayon
 
NOTE: 'bzr pull' is a special command that overwrites the local branch with
new content from the pull source. Because this overwrites the local branch,
it is not advisable to use it beyond the first update. For getting future
updates from trunk you should use the 'bzr merge' command.
 
For more information, see:
  $ bzr merge --help
 
 
INSTALL AGASTI
==============
 
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 /home/agastidev/Desktop/sahana-agasti-mayon/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 www-data php /home/agastidev/Desktop/sahana-agasti-mayon/apps/frontend/lib/util/wiki-auth-setup.php
 
Finally, generate the wiki indexes by running the following command:
 
  $ sudo -u www-data /home/agastidev/Desktop/sahana-agasti-mayon/web/wiki/bin/indexer.php -c
 
  * NOTES:
 
    - You can safely ignore any PHP warning of the form:
      PHP Warning:  parse_url(http:///web/wiki/bin/): Unable to parse URL in ...
 
 
GOING FORWARD
=============
Now that you have a working installation... Explore! Have fun! Fire up
netbeans and make your wildest imagination come true!
 
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 branch root:
 
  $ cd /home/agastidev/Desktop/sahana-agasti-mayon
  $ ./symfony cc
 
  and try again.
 
- 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/