# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1628613406 -7200
# Node ID 33d7833ca54ca55720def9427abefb68f8f1e6a9
# Parent  1f7e76a213dd766d5e86db287a4c41ad24127f7e
#102 add installation instructions

diff -r 1f7e76a213dd -r 33d7833ca54c INSTALL
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/INSTALL	Tue Aug 10 18:36:46 2021 +0200
@@ -0,0 +1,56 @@
+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!