Installation Guide - BETA
This document will explain all the steps required to install the Virtual Planner web application onto your web server. If you encounter any problems not covered by this guide, please contact us.
Requirements
- PHP version 5.2.3 or above.
- Phing
- Apache 1.3 or 2.2.
- PostGres? 8 or MySQL 5 (SQLite will not work).
- "sudo" (or root) access to the server.
- Apache configured to use PHP.
- (Optional) - APC PHP extension installed.
- Python 2.4 or above.
- Trac 0.10 or above.
- "Timing and Estimation" Trac plug-in (see bottom of this page).
If you've not performed a global installation of PHP, please note that the php command needs to be accessible via one of the directories in the PATH environmental variable, because it is used to run some parts of the Virtual Planner installation from the command line. The same goes for the database: "mysql", "psql", etc, needs to be accessible from the command line.
Web Application
Stage 1
In these examples, the directory /var/www/ will be used as the root of the web server's directory. We will assume that you check out the project itself in your home directory ($HOME). When performing the installation, please change as appropriate.
Navigate to the installation directory (/home/something/) and perform an SVN "checkout" on the Virtual Planner's repository.
sam@mort:~$ svn co http://virtual-planner.palepurple.co.uk/svn virtual-planner
At this point, you will see a great many files being downloaded into a newly created directory called virtual-planner - this directory can be renamed once the checkout process has been completed, should you so choose. Due to the large number of files, the checkout process may take several minutes - depending on the speed of your internet connection.
Once the checkout has finished, change into the trunk directory (which is a sub-directory of virtual-planner directory) and list the contents. You should see something similar to this:
sam@mort:~$ cd virtual-planner/trunk sam@mort:~/virtual-planner/trunk$ ls app config db lib LICENCE.txt public setup.sh trac-python-plugin var
Stage 1.1 - File Permissions
For now, you can quite happily ignore all of the files but one: setup.sh. That file is a shell script which performs the very first step of configuring the application and must be run before anything else can continue. Although it is very important, it is very simple: it merely creates some directories and files that are needed by the application, then sets the correct permissions on them so that the user under which the Apache daemon runs can access them.
When running the script, it assumes that you have sudo rights and will ask you for your password; if you've recently used sudo, you will see a different output to the below.
sam@mort:~/virtual-planner/trunk$ sh setup.sh
Changing "var" dir to chgrp www-data (web server group)
We trust you have received the usual lecture from the local System
Administrator. It usually boils down to these three things:
#1) Respect the privacy of others.
#2) Think before you type.
#3) With great power comes great responsibility.
Password:
Changing "var" file permissions to 775
Changing "var" dir to chmod g+s,
Setup complete
If you do a detailed listing of the directory (ls -lh), you should see that the directories db and var are now owned by the group "www-data". If your system runs Apache under a different user, you will need to correct these permissions with the "chgrp" command.
sam@mort:~/virtual-planner/trunk$ sudo chgrp -R apache db var
Stage 1.2 - Making it available to the web server
Next, you need to symlink the virtual-planner/trunk/public directory into your web-server, so it's reachable through a web browser.
sam@mort:/var/www$ sudo ln -s /home/sam/virtual-planner/trunk/public virtual-planner
If you now access http://yourserver you should see a 'virtual-planner' directory. You may need to tell Apache to FollowSymLinks? for this to work.
Stage 1.2.1 - Configuring Apache
Due to the way Virtual Planner works, it needs Apache to follow certain rules. That is; it needs to route all requests through the Dispatch.php, which it does through the .htaccess file - both files are located in the trunk/public directory. Thankfully, you don't need to directly deal with either of these files - but you do need to tell Apache to follow the rules laid out in the aforementioned .htaccess file.
To do this, edit the appropriate Apache configuration file. This can either be the virtual-host configuration file, or, if you don't have one set-up, the configuration file that handles the overall Apache settings. For example:
<Directory /home/sam/virtual-planner/trunk/>
AllowOverride All
</Directory>
Restart Apache and it should take effect.
Stage 1.3 - Web based configuration
From this point on, the configuration of the web application is done through a web browser - go to http://yourserver/virtual-planner.
All being well, your browser should connect to your web server and give you the following message:
/path/to/virtual-planner/trunk/lib/init.php: Can't find project settings; have you run propel build?
Do not worry - *that is normal*. In your web browser, append "setup/" to the URL/address (it should now look like this: "http://yourserver/virtual-planner/setup/") - this is where the next stage of the configuration process takes place.
If you are not running the required version of PHP, the script will warn you of this fact and stop. This application will not run if you do not have at least version 5.2.3 of PHP. Until you upgrade, you cannot continue with the Virtual Planner configuration. If you version of PHP is sufficient, this step will be transparent.
It will then move on to checking the permissions of certain directories. If you have run the setup.sh script as explained above, this will show nothing - otherwise you will be given an error about file permissions. Should you encounter this problem, check that the directories db and var are owned by the "www-data" group. If they are; check that your httpd daemon is indeed running under that user. If not, change the directories' group to be that of the http daemon's user's group (the name of the user should be given in the error message).
Stage 1.3.1 - Database settings - through the semi-automated web form
Once all permissions have been dealt with (if there were actually any problems with them), you will be greeted by a form asking you for the connection details for the database server. This is where things get slightly more technical, because you need to know them - or at least have access to them.
Thanks to the database abstraction layer provided by Propel (an ORM used by the Virtual Planner), the application can utilise several different database types: MySQL, PostgreSQL, MS SQL, etc. It is important to note that, SQLite is unfortunately not supported at this time! We recommend using PostgreSQL, but MySQL is also a good choice.
For the examples in this guide, the following details will be used:
- Host: localhost
- Port: (blank - use default)
- Database name: virtual-planner
- User name: virtual
- Password: planner
The database type will be PostGres?.
You'll have hopefully noticed the text to the right of the "Database Name" field stating that it "must exist". That is to say that a database of the given name must not only exist on the database server (at the given address), but that the user (whose details you supply) has full access to it. The user needs CREATE, DROP, INSERT, UPDATE, SELECT, etc.
This web interface is not the only way to set up the database connection details, as implied by the "I've edited the files by hand - skip this stage" link just under the title. For details on editing the files by hand, skip the next paragraph.
Once you have filled out all of the required fields (all but "Port" are required), click the "Submit" button. If all goes to plan, the settings should be written to the appropriate files (see below for more details) and it will attempt to connect to the database. If that is also successful, it'll redirect you to stage 2 of the process - a much brighter looking page. If you get here, skip to the section titled "Stage 2".
Stage 1.3.2 - Database settings - for Luddites!
You're still reading, so either something went wrong or you don't wish to use the web-based form. I'll deal with the latter first.
There are two files that need to be altered before the configuration process can continue: build.properties and runtime-conf.xml, both of which live in the db/propel/ directory. Both files are plain text files that can be edited in any normal text editor, such as Pico, Nano, Vi[m], Emacs, etc., and come with sample data already filled in.
It is assumed that if you're editing these files, you know what you're doing - the files should be straight-forward as far as what information needs to go where. If you're having difficulties, either use the web interface or contact us.
Troubleshooting
The main problem to occur at this juncture is the inability to connect to the database with the supplied information. If such a problem arises, check that you have entered the details correctly (simple, but mistakes happen). Secondly, try connecting to the database via the command-line (or GUI, if you prefer) tools for your database.
It is also worth noting that the command to run the database tools (mysql, psql, etc) must be in the PATH so that Propel can access them. If they're installed outside of the PATH, you will need to add their directory to it before the next stage.
If you are encountering problems other than database connection issues (IE; PHP errors, or the like), please contact us.
Stage 2
Stage 2 starts off with a page that looks a lot more interesting than the previous one(s); you should have a title bar and a purple menu down the left. Refrain from clicking any of the links at this point in time, since they won't work just yet. If you see something different, please look at the "Troubleshooting" section below.
At this point, the application has been able to connect to the database, but there won't be any data in it - that's where stage 2 comes into play. This stage will perform two simple, but vital, tasks: create a new user account (so that you can log in) and create "weeks" (don't worry about these for now).
In the middle of the page will be two input boxes; one for the user name and one for the password. This is where you enter the details of the Virtual Planner user you wish to created. By default; user names must be at least three characters long and passwords need to be six or more characters long. Once you've entered the data, click the Create button and you should be taken to yet another page - the final page!
You shouldn't need to do anything on this page; unless something went wrong on the previous page (such as a user name and/or password that didn't meet the length criteria). You should, however, get:
- Confirmation that the user was created
- Confirmation that several "weeks" were created (see the UserGuide for more details on "weeks")
- The URL of the "notification target" - keep that safe!
- A message saying setup is complete
- A login form
Using the user name and password of the user you just created, log in to the application - the menu down the left-hand side should now work; although there will be very little data in the database. See the UserGuide for information on what the different pages do.
Troubleshooting
At this point, you may once again be greated with the following message:
/path/to/virtual-planner/trunk/lib/init.php: Can't find project settings; have you run propel build?
This means that the end of stage 1 couldn't be performed automagically (probably because the user under which Apache is running doesn't have permissions to create files in db/propel/, or that it can't find some of the required libraries). This isn't a problem, since it's easy enough to fix by hand. All you need to do is run the following command: (you need to have write permission to db/propel/)
sam@mort:~/virtual-planner/trunk$ sh db/propel/build.sh
This should fill your screen with lots of text - feel free to ignore it if you so choose. Having said that; watch out for any red text - red text is used to high-light errors. If you do see any red text, press Ctrl+C to cancel the build script and read what the errors say. If you don't know how to resolve the errors, feel free to contact us.
At the half-way point, it will pause and give you a five-second count down, warning you that your database will be altered. Let this run its course - ignoring any red text from this point on. If this is the first time you're running the script, it will almost certainly throw up some errors - but these are just stating that it cannot drop the tables from the database (which is because they don't yet exist). If in doubt, re-run the build script a second time - it should now all be error-free.
Phing
If it mentions that it cannot find "Phing", ensure that Phing is installed. If it's not installed, you can do a global install by simply running the following commands: (they obviously require "PEAR" to be installed)
sam@mort:~/virtual-planner/trunk$ pear channel-discover pear.phing.info sam@mort:~/virtual-planner/trunk$ pear install phing/phing
Once that has completed, re-run the build script. If the installation of Phing fails, or you don't have PEAR installed, please visit their respective sites for more info. Phing is only needed for this small (but important) part of the installation process, so you may not want to perform a global installation of it. To download the packages and install it by hand, please visit their site here: http://phing.info/trac/wiki/Users/Download
Local installation of Phing will need some environmental variables to be set so that Propel can find and use it. Before running the build script ("db/propel/build.sh"), try running these commands: (remember to replace "/PATH/TO/" with the real path to where the files are located and replace "phing-2.3.0" with whichever version of Phing you are attempting to use)
sam@mort:~/virtual-planner/trunk$ PHING_HOME=/PATH/TO/phing-2.3.0 sam@mort:~/virtual-planner/trunk$ PHING_COMMAND=/PATH/TO/phing-2.3.0/bin/phing
Creole
It's also possible that it can't find "Creole", despite the fact that it is included as part of the Virtual Planner. It may be possible to solve this problem by changing the PHP_CLASSPATH environmental variable to include the path to Creole. Try the following command, then re-run the build script:
sam@mort:~/virtual-planner/trunk$ PHP_CLASSPATH=$PHP_CLASSPATH:~/virtual-planner/trunk/lib/creole/creole-1.1.0/classes
You can solve this by installing it globally via PEAR:
sam@mort:~/virtual-planner/trunk$ pear channel-discover pear.phpdb.org sam@mort:~/virtual-planner/trunk$ pear install phpdb/creole sam@mort:~/virtual-planner/trunk$ pear install phpdb/jargon
Misc
If you're encountering different problems, or if the above didn't solve your issues, please let us know and we'll do our best to help you fix it.
Protection
The "notification target" is the page called by the Trac plug-in to update the Virtual Planner. This should obviously not be readily accessible to the public, since it could allow users to corrupt the data. To solve this problem, we recommend using Apache's "htpasswd"/"htaccess" features.
Details to follow.
Important "Final" Step
"Final" as far as the web-application side - you still need to do some stuff with Trac; see below.
Since the setup process you've just been through allows you to specify the database connection details, it's not something you want to leave on your server for anyone else to access. It is therefore very important that you remove the "setup" directory once you have completed this installation process. The setup directory lives in ... /virtual-planner/trunk/app/controller/.
Congratulations; you've completed the first half of the Virtual Planner installation! If you're feeling up to it; move on to the Trac Configuration section - otherwise, take a rest and have a cup of tea. :)
Trac Configuration
You now need to change the configuration of Trac itself, telling it to load a new plug-in. The plug-in's task is rather simple; whenever a ticket is altered (created, edited, deleted), it will send off the information to the Virtual Planner - that's how it keeps the information up-to date. For a much more technical look at the notification plug-in, please visit the NotifyPlugin page.
Stage 1
Make your way to the trunk directory of the Virtual Planner and list the contents, you should see something such as:
sam@mort:~/virtual-planner/trunk$ ls app config db lib LICENCE.txt public setup.sh trac-python-plugin var
Now move in to the trac-python-plugin directory. There are two ways you can continue from this point: a) editing and building the plug-in by hand (hard), or 2) using the nice script to help you (easy). For method a), see the NotifyPlugin page. For 2), continue reading.
The script that configures and builds the plug-in for you will ask three questions. It will want to know:
- The full address of the "notification target", which should have been given to you at the end of the web application installation process.
- User name to access to aforementioned notification target.
- Password which goes with the above user name. WARNING: Your password will not be masked!
Another point worth mentioning is that once the plug-in has been build, the script will try to install it to /usr/share/trac/plugins/. If you do not have write permission to this directory, this step will fail. You can of course copy the file to this directory by hand at a later date, so it's not a major problem. If you do not want the plug-in to be installed into this directory (if, for instance, that's not where Trac lives on your system, or you only want it installed for one instance of Trac), please edit the build.sh file in this directory and comment out the last line (which should look like: "cp dist/*.egg /usr/share/trac/plugins").
Next, run the configure.py script and follow the on-screen prompts. Here's an example of what it should look like: (the middle part has been omitted since it's quite long)
sam@mort:~/virtual-planner/trunk$ configure.py Please note that if you want this plug-in to be automagically installed in to Trac's directory, you *must* have write permission to that directory (typically '/usr/share/trac/plugins/'). If you do not, the final part of the build process will fail. See the documentation for more info. Please input the address of the 'notification target': http://snakes.onaserver.org/virtual-planner/ping/update.php Please enter the user name to acces the notification target: planningboard Please enter the password to acces the notification target: xxxxxxxxx Plug-in configured, building the egg... + set -e + rm -Rf build + rm -Rf dist + python setup.py bdist_egg running bdist_egg running egg_info creating TracNotify.egg-info writing TracNotify.egg-info/PKG-INFO ...<snip>... creating dist creating 'dist/TracNotify-0.1-py2.5.egg' and adding 'build/bdist.linux-x86_64/egg' to it removing 'build/bdist.linux-x86_64/egg' (and everything under it) + cp dist/TracNotify-0.1-py2.5.egg /usr/share/trac/plugins All done (unless you saw errors from the build process). You can now feed the plug-in's egg to Trac.
Stage 2
Edit (or create) /usr/share/trac/conf/trac.ini (the path will be different if you've installed Trac to somewhere else), it should look like (or at least contain):
[components] notify.* = enabled
Stage 3
You will also need to install the "Timing and Estimation" plug-in for Trac, which can be found here: http://trac-hacks.org/wiki/TimingAndEstimationPlugin
