This chapter will teach you to install the Plandora. The Plandora is a web tool, client-server and for this reason, it demands a little more complex configuration, but should not be a big deal.
First of all, you should have two things: a web server and a database. In developing time, the Plandora uses the Tomcat and MySQL respectively, but you can host the Plandora into another web server (Servlet compatible). Bearing in mind that you can choose another web server but you may find some initial difficulty, especially in data source configuration because this 'setup package' only contains the configuration for Tomcat. Nevertheless, feel free to choose another database but remember that Plandora was tested only in MySQL.
This release package contains:
FIRST STEP: Getting the Tomcat and MySQL
This zip file might contains:
- pandora.war: which will be used to 'publish' the tool into web server.
- MYSQL.sql: DON'T USE THIS SCRIPT if you have a previous Plandora! This file contains the SQL script for creation of table and some basic data. You should use this script only for a NEW installation.
- READ-ME_FOR_MIGRATION_FROM_v1.12.0: If you are updating your Plandora version from version 1.12.0, read this file to learn how to migrate to version 1.12.0 preserving the current data.
- server.xml or context.xml: This file should be used for data source configuration purposes of Plandora into Tomcat
- release_notes.txt: The release notes file about the current version
- plandoraInterface.jar: This file can be used by developers in order to extend Plandora features or to customize specific points of system (ex.: notificator, knowledge base, project occurrence, etc)
- other_db_scrips_BETA.zip: this zip file contain SQL scripts to other databases (Postgres, HSQL, etc). The default database of Plandora is MySQL but it is able to use other databases.
The source files of tool
Both tools are open source and for this reason, it can be downloaded from the Internet freely and used without any cost. These tools are strongly consolidated and are of stable implementation.
We recommend using the version 5.5.30 for Tomcat and 5.0 for MySQL. These versions were stressed and successfully used during the tests.
The link to perform the Tomcat download is the Jakarta web site (a community that is part of Apache Group, which implements and controls the Tomcat besides many other interesting tools):
The link to perform the MySQL download of MySQL is the MySQL website: http://dev.mysql.com/downloads/mirrors.html
After downloading, you should install everything into the machine that will be the Plandora server. You can install the Data Base and Web Server in the same machine or separately. This decision should be based on your needs. Feel free to choose what best fits your needs.
For Windows installation, the Tomcat is a simple Zip file. To perform the installation, unzip the file into your machine's file system.
For Windows MySQL, there is a Setup application, which after execution, requires some information such as: database user and password and database type (choose the 'WebApplication' type)
Obs.: After the Windows installation, the MySQL will be installed as a Windows Service. This feature makes startup, shutdown, managing, logs, etc, easier.
SECOND STEP: Running the data base script
You should open the 'client screen' of MySQL. If you have used the Windows installation, this 'client screen' is accessible through 'Start' button ('MySQL Command Line Client'). After opening it, the 'client screen' will ask for a database password. You should enter the same password that you have created previously. Then, the database will display the prompt ("mysql>").
Then, type: create database plandora;
And you might receive the response: Query OK, 1 row affected (0.01 sec)
With this command, you've just created a new 'database' object, and it is ready for data insertion.
Then, type: use plandora;
And you might receive the response: Database changed
This line means that you are saying to the database that everything that you will do from now on, will be done within the database called 'plandora' which was previously created.
In order to complete the process, you should create the Plandora tables and insert some basic data, but bear in mind that if you are updating the version of Plandora DON'T USE THE 'MYSQL.sql' script. You must use the apropriate script to upgrade the tool version and preserve the current data. On the other hand, if you are performing a new installation, use the 'MYSQL.sql' script unziping the file 'Plandora-vX.X.X.zip' to a known place and typing this command into MySQL client: source [path_where_you_unziped]/mysql.sql;
Wait until all data population is done. After that, close the client screen through the command: quit
THIRD STEP: Starting the Tomcat
Copy the file mysql-connector-java-5.1.10-bin to the folder common/lib/ of Tomcat. This is the library for MySQL data base access used by Tomcat. This lib is called ConnectorJ and can be dowloaded at http://dev.mysql.com/downloads/connector/j/5.1.html
The next step is to setup the Data Source. Tomcat will need this information for connection purposes and to supply a connection to the application. Actually the Tomcat takes the control of the data base 'connection pool'.
For Tomcat 5.0.x you should copy the server.xml (that comes with the installation package) to the folder conf/ of Tomcat.
For Tomcat 5.3.x or higher you SHOULD NOT copy the server.xml but you should edit the context.xml (get the example file that comes with the installation package) file into the folder conf/ of Tomcat.
Note 1: In both cases, it is necessary to change the fields user and password to the appropriate user settings that you have created during the Data Base installation.
Note 2: Also check if the field url contain the appropriate value. The standard files consider the name of database, "plandora" (jdbc:mysql://localhost:3306/plandora), but maybe you prefer to change this configuration. Regardless, it is very important to keep the name of the tag resource with value jdbc/plandora.
After unzipping the file 'plandora-vX.X.X.zip', the file 'pandora.war' will be created. Copy to folder /webapps of Tomcat. After that, start the Tomcat through 'startup.bat' (windows) or './startup.sh' (Linux) that is placed into Tomcat bin/ folder. After a few seconds (and many screen messages), the message below should pop up on the Tomcat console: 'INFO: Server startup in xxxx ms'. When this message pops up, it means that Tomcat is already started up and your machine is now a Web Server.
In order to test, open a browser and type into 'Location Bar': "http://localhost:8080". Notice that we excluded the fragment 'www' because we are accessing locally. If a standard page of Tomcat pops ups, it's working!
Note 3: If you are running Plandora at Centos 5.4, also consider checking the JAVA_OPTS parameters of Tomcat (see more about it here).
Note 4: If you are running Plandora at Tomcat 6.0.14, eventually consider placing the context.xml at /META-INF folder. (see more about it here).
Note 5: If you are running Tomcat in combination with Ubuntu and MySQL, please consider this post.
Note 6: If you are running Tomcat at Linux, please consider the parameter -Djava.awt.headless=true during Tomcat configuration to prevent bugs in Plandora report feature. More infomation here.
Note 7: If you are running Tomcat at Fedora 15, please check if all libs have been installed. More infomation here.
LAST STEP: Starting the Plandora
If everything is working with Tomcat, it should have been exploded the file pandora.war (that you have been put into /webapps folder) in a 'pandora' folder into the /webapps. This compartment is called 'application deploy'. Make sure that the Plandora deploy happened, and then, open a browser and type:
It should display the login form of Plandora. Use the user 'root' without password to create new users and projects. Also, click at 'Options' link and edit the field 'Knowledge Base Index Files Folder' to a path that make sense to your environment.
There are some users for testing. All of them have no password. You can remove or change if you want. Remember, from now on (until you shutdown your Tomcat ;-) ) your machine is a web server that can be accessed by other machines in your network (or even by the Internet depending on your network settings) through the IP number or the machine name.
To do this, type the address below in another machine (client machine) in order to access Plandora:
Have a nice project!