Preface

Author: $Author$
Version: $Revision$
Location: $URL$

Scope

This document describes how to set up the LiveSupport development environment.

Introduction

LiveSupport uses a well-defined development environment. Most of the LiveSupport-specific files are included in the version control system, but some preparation and setup has to be made on system used to develop LiveSupport as well.

There is a simplified and Ubuntu-centric version of this document in the LiveSupport Trac wiki.

Steps

The following steps needed to be taken for setting up the LiveSupport development environment.

install development tools
set up additional system resources
check out the sources
configure the environment
set up tools used by LiveSupport
personalize your development environment

Install development tools

Install all the tools needed for the development of LiveSupport. Please see the development tools document for a list of tools needed.

Set up additional system resources

The LiveSupport development environment uses some system resources, that are not reasonable to include in the environment itself.

Test database

One such resource is an ODBC datasource to a test database. This database has to be accessible for executing the test suites and applications within the LiveSupport development environment.

First, LiveSupport expects a PostgreSQL database, and an ODBC Data Source accessible to it through unixODBC. Please refer to the documentation of these tools to set them up.

The test environment assumes that it can connect to the PostgreSQL database as localhost via a TCP/IP connection, as the user test.

In newer versions of PostgreSQL (≥ 8), TCP/IP connections from localhost are enabled by default. If you are using an older version, do the following:

edit postgresql.conf (usually /var/lib/postgres/data/postgresql.conf), to have to following line:
```
tcpip_socket = true
```
and also edit pg_hba.conf (usually /var/lib/postgres/data/pg_hba.conf) to include the following line, before other lines related to access through localhost:
```
host    all         all         127.0.0.1         255.255.255.255   password
```
After the above two manual edits to the PostgreSQL configuration, restart the postgresql daemon.

Web server

Second, LiveSupport expects:

Apache httpd server running on the development computer
PHP interpreter
PHP apache module
PHP iconv extension (--with-iconv)
DOMXML PHP extension - an XMLv2 module for PHP
PostgreSQL support in PHP
PEAR

Apache group membership

The setup script assumes that the current user is a member of the Apache group. Add the user who will be using the development environment to this group; it's usually called apache; on debian-based systems, it is called www-data.

Apache configuration

The storage server uses some directives which are not enabled by default. To enable them, find the configuration file for the userdir module of apache, and change the AllowOverride directive in the <Directory /home/*/public_html> section to All.

Check out the sources

The LiveSupport development directory tree can be accessed anonymously via Subversion, at svn+ssh://code.campware.org/home/svn/repo/livesupport/trunk/livesupport. The following Subversion command would check out the development tree:

svn checkout svn+ssh://code.campware.org/home/svn/repo/livesupport/trunk/livesupport

This will check out and create the LiveSupport development directory structure.

Configure the environment

First, you need to create the database and ODBC data source used by LiveSupport. This is done most easily by running the script livesupport/bin/user_setup_db.sh. Run the scripts as root, and provide your user name with the --user option:


cd livesupport
sudo ./bin/user_setup_db.sh --user=<ls_developer_user>

The script will set up the following resources:

a PostgreSQL user named test with the password test (if it does not exist)
a PostgreSQL database named LiveSupport-<ls_developer_user>
an ODBC data source of the same name, with user name and password test

Next (and last), you compile the code and set up the configuration files. Both are done by the script


cd livesupport
./bin/setupDevelopmentEnvironment.sh --apache-group=<apache_group>

This script will set up the libraries used by LiveSupport (by compiling and installing them under livesupport/usr), and set up the development environment for all LiveSupport modules.

It will also create your personalized configuration files under ~/.livesupport, make certain directories writable for Apache (this is where we need the current user to be a member of the apache group), define a user-specific port for the scheduler daemon, and create a symlink in ~/public_html/ to the PHP entry points.

After running the above script, the livesupport development environment for the current user will be unique on the system, and will not conflict with resources used by other developers. For example, the LiveSupport HTML user interface for the user will be reachable at:


http://localhost/~<ls_developer_user>/livesupport/htmlUI/var

Single-user setup

It is also possible to set up a shared configuration, instead of the per-user setup described in the previous section.

To do this, use the script test_setup_db.sh instead of user_setup_db.sh. You will also need to manually execute the commands in setupDevelopmentEnvironment up to, and not including, the call to user_setup.sh; and manually execute the "Setup storage server" and "Setup directory permissions" portions of the user_setup.sh script. Finally, create a symlink livesupport in the root data directory of the Apache server which points to livesupport/src/modules/. The address of the HTML interface will now be


http://localhost/livesupport/htmlUI/var

After this, the development environment should work, using the default configuration files. NOTE: this single-user method has not been used by any developers for quite some time, so these instructions may be out of date or incomplete.

Ready to roll

With the above steps completed, the LiveSupport modules and products are ready to be compiled and developed further. Have fun!