INSTALL

Installing LightPIT
-------------------

1. Install a supported database server

Currently this is only Postgresql. See the Postgresql manual for installing a
database instance. On most systems it is sufficient to install the server via
the system package manager.

2. Execute the SQL scripts for creating the database

In the setup directory you find three SQL scripts to install the database.

* Modify psql_create_database.sql and choose appropriate usernames and
  passwords. Then execute the script as database administrator.
* Log into the new database with the lightpit_dbo user and execute
  psql_create_tables.sql and psql_default_data.sql.

3. Configure a data source in your application servlet or servlet container

You may use absolutely anything: Tomcat, TomEE, Glassfish, Payara, you name it.
Just make sure to configure a data source with the name jdbc/lightpit/app.
If you want another name, you can configure the JNDI resource in the
WEB-INF/web.xml and META-INF/context.xml files. It is highly recommended to use
the lightpit_app user which has less privileges to create the data source and
leave the lightpit_dbo user for the database operator.

4. Make sure JDBC driver and JSTL libraries are available

This step may be optional depending on the container you are using. Most
application servers already have JSTL libraries installed. More basic servlet
containers like Tomcat don't. In that case you have to put the libraries of the
javax.servlet:jstl:1.2 artifact manually into the library dir of your servlet
container (jstl-1.2.jar and jstl-impl-1.2.jar).

In most cases you also have to put the postgresql JDBC driver into the library
directory of your server (e.g. postgres-42.x.x.jar).

5. Deploy the WAR file of lightpit

This is the most straight forward step. Just deploy the WAR file as you usually
do in your application server.

6. Configuring a web server and authentication

LightPIT can optionally detect the authenticated user. You may freely decide
whether to enable authentication in your application server or put a web server
in front. The latter is recommended, but keep in might that forwarding the
authentication information may only work with AJP for certain servlet
containers. Consult the respective manuals of the software you are using.

When the remote user is picked up successfully by LightPIT, comments under
issues e.g. are personalized. For this to work the authenticated username must
match one of the configured usernames in LightPIT.

Have fun!