From GTwM

This page is part of the agileBase documentation.

This page is intended for technical users to provide help in installing a standalone version of agileBase on a server, as an alternative to using a hosted service. Knowledge of technologies used is assumed. Please run through these instructions in order. There are quite a few steps but each one is simple.

Contents 1 Prerequisites 1.1 Prerequisite setup 2 Build 2.1 Download 2.2 Build Serverside 2.3 Build clientside 3 Pre-run setup 3.1 Databases 3.2 Tomcat 4 Setup 5 Post-run setup 6 We're there!

Prerequisites

agileBase will run on Linux, Windows, OS X or in fact any operating system that supports Java and PostgreSQL.

• Java 1.5 or above - including the development environment for compilation
• ant
• PostgreSQL
• A servlet container - tested with Apache Tomcat
• The YUI compressor http://developer.yahoo.com/yui/compressor/
  • Optional but recommended

Prerequisite setup

• Ensure Tomcat installation is running successfully
• Download the latest database driver from http://jdbc.postgresql.org/
• Place the driver .jar file in Tomcat's /lib folder

Build

Download

• Get the latest version from the download facility on the source control site https://github.com/okohll/agileBase
• Unzip into a folder you can use for compiling, e.g. /usr/local/agileBase

Build Serverside

• Enter the gtpb_server folder
• Edit the file velocity.properties
  • Alter the start of the file.resource.loader.path property, i.e. /usr/local/tomcat/apache-tomcat/ to match the location of your Tomcat installation
• Create a copy of the build file to tailor to your installation

cp build_redhat.xml build_custom.xml

• Edit the build_custom.xml file
• Alter the directory components at the top of the file to suit your system
• Shut down Tomcat
• Build with ant

ant -f build_custom.xml deploy

This should compile and deploy the required Java files and resources to Tomcat

Build clientside

• Enter the gtpb_clienside folder
• Edit website/index.shtml
  • Edit line 80 and replace the key with a Google API key valid for the domain you'll be running agileBase on
    • Generate a key at http://code.google.com/apis/maps/signup.html
  • Edit line 222 an replace https://appserver.gtportalbase.com/ with your domain
• Edit WEB-INF/templates/gui/resources/google_maps_api_key.vm and enter your key there
• Create a copy of the build file to tailor to your instalation

cp deploy_templates_redhat.xml deploy_templates_custom.xml

• Alter the tomcat.dir property in that file to match your system
• Create a copy of deploy.sh

cp deploy.sh deploy_custom.sh

• In deploy_custom.sh, remove the cvs update line
• Also change the reference to deploy_templates_redhat.xml to deploy_templates_custom.xml
• Alter the paths in the rest of the lines to match your system
• Run the deploy_custom.sh file

This should copy the GUI template files to the correct location in Tomcat and compress them for improved download speed.

Note for debugging, you may want to comment out the compression lines but they're recommended for production use.

Pre-run setup

Databases

• As a postgres superuser, create the user/role gtpb using the SQL

CREATE USER gtpb WITH PASSWORD 'gtpb';

• Create two databases

create database agilebasedata owner gtpb;
create database agilebaseschema owner gtpb;

The first is the store the user data, i.e. any tables and views created by portalBase. The second is used by portalBase to store metadata about the objects in the database

• Find the three files in gtpb_server/scripts/portalbasedata_setup
• Run each on the portalbasedata database as the user gtpb

psql -U gtpb -d agilebasedata -f 1_create_log_tables.sql
psql -U gtpb -d agilebasedata -f 2_gtpb_divide.sql
psql -U gtpb -d agilebasedata -f 3_dbint_report_view_stats.sql

Tomcat

• Edit the server.xml configuration file in Tomcat's conf folder
• You should see a <Host> entry near the end, which starts something like

<Host name="localhost" appBase="webapps"
          unpackWARs="true" autoDeploy="true"
          xmlValidation="false" xmlNamespaceAware="false">

• Inside that Host entry, i.e. just before </Host>, enter the lines

       <Context path="/agileBase" docBase="agileBase" debug="0" reloadable="false" crossContext="false" privileged="true">   
        <Resource name="jdbc/agileBaseData" auth="Container" type="javax.sql.DataSource"
              maxActive="50" maxIdle="5" maxWait="10000" username="gtpb" password="gtpb"
              driverClassName="org.postgresql.Driver" url="jdbc:postgresql://localhost/agilebasedata" />
        <Resource name="jdbc/agileBaseSchema" auth="Container" type="javax.sql.DataSource"
              maxActive="10" maxIdle="5" maxWait="10000" username="gtpb" password="gtpb"
              driverClassName="org.postgresql.Driver" url="jdbc:postgresql://localhost/agilebaseschema" />
        <Realm className="org.apache.catalina.realm.DataSourceRealm"
          debug="99" dataSourceName="jdbc/agileBaseSchema"
          localDataSource="true" userTable="appuser"
          userNameCol="username" userCredCol="password"
          userRoleTable="dbint_user_roles" roleNameCol="rolename" />
      </Context>

Setup

You should now be able to run portalBase and perform the further necessary setup within the application itself

• Start up (or restart) Tomcat
• Check the Tomcat log to ensure correct startup

tail logs/catalina.out

The portalBase application should be running. To check that it booted up ok, connect to the portalbaseschema database. You should be able to see a host of newly created tables

psql -U gtpb portalbaseschema
\d

• Check that the login page is visible
  • Go to http://myserver.com/agileBase/AppController.servlet?return=gui/load_tabs - obviously replacing myserver.com with the domain name or IP address of your server
  • The page should look like http://www.agilebase.co.uk/
  • If it looks ok, you can create a redirect or shortcut to this with your web server

Post-run setup

Before logging in, one action is necessary:

• Shut down Tomcat
• Find the script gtpb_server/scripts/agilebaseschema_setup/1_add_user_roles.sql
• Run it for the agilebaseschema database

psql -U gtpb -d agilebaseschema -f 1_add_user_roles.sql

Now we can log in.

• Connect to the agilebaseschema database and use SQL to find the password of the master user. agileBase will have created this user and assigned a random password.
  • In agilebaseschema

SELECT * from appuser;

• The username will be 'master' and the password will be listed
• Log in at the URL http://myserver.com/agileBase/AppController.servlet?return=gui/load_tabs&set_context=sysadmin

Note: you will only ever need to log in with the username 'master' during setup so you don't need to change the password to something more memorable. agileBase allows you to set up one or more companies whose data will be separated from each other - you may only need to set up one, which we'll do now...

• Press the Dev Tools button at the top right of the toolbar. Note the dev tools are not for everyday use and therefore are not pretty like the rest of the application!
• Select Manage Companies
• Enter the name of your organisation and press 'Add Company'. The company name should appear below
• Close the development tools and log off
• agileBase will now have created a user for that company. Again, log in to agilebaseschema manually to find the username and password
  • In portalbaseschema

SELECT * FROM appuser;

We're there!

• You can now log in to agileBase with that admin username and password at the URL http://myserver.com/agileBase/AppController.servlet?return=gui/load_tabs

Carry on at the general documentation agileBase. You may like to start with Privilege management or Tables and fields under the administration section.