Table of Contents
Developer's Live Disc
Introduction
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.
How to Download
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.
System Requirements
Disk Space
Required | Recommended | |
---|---|---|
Downloaded ISO | 900MB | 900MB |
Installed | 3GB | 8GB |
Memory Requirements
Required | Recommended | |
---|---|---|
Live Disc | 768MB | 1GB |
Installed | 768MB | 2GB |
Virtualization Requirements (Optional)
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.
What's Included?
Notable software found on this Live Disc include:
Netbeans IDE | Our integrated development environment of choice, pre-configured to load your new agasti project |
---|---|
Apache HTTPD | The venerable Apache2 http server |
MySQL | Our database server of choice |
Bazaar VCS | The bazaar version control system (how we track this project on Launchpad) |
Firefox | A great, standards-based web-browser with several useful default bookmarks |
XDebug | A PHP5 extension that integrated with Netbeans to provide debugging and step-through functionality |
Firebug | A Firefox plugin that shows advanced debugging information for webpages |
XChat | Internet relay chat (IRC) client |
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/.
Recommended Usage
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.
Official Support
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.
Example ReadMe.txt
- 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/