universe@221: Installing LightPIT
universe@221: -------------------
universe@221: 
universe@221: 1. Install a supported database server
universe@221: 
universe@221: Currently this is only Postgresql. See the Postgresql manual for installing a
universe@221: database instance. On most systems it is sufficient to install the server via
universe@221: the system package manager.
universe@221: 
universe@221: 2. Execute the SQL scripts for creating the database
universe@221: 
universe@221: In the setup directory you find three SQL scripts to install the database.
universe@221: 
universe@221: * Modify psql_create_database.sql and choose appropriate usernames and
universe@221:   passwords. Then execute the script as database administrator.
universe@221: * Log into the new database with the lightpit_dbo user and execute
universe@221:   psql_create_tables.sql and psql_default_data.sql.
universe@221: 
universe@221: 3. Configure a data source in your application servlet or servlet container
universe@221: 
universe@221: You may use absolutely anything: Tomcat, TomEE, Glassfish, Payara, you name it.
universe@254: If it supports Servlet 6.0, JSP 3.1, and EL 5.0, you are good to go.
universe@221: Just make sure to configure a data source with the name jdbc/lightpit/app.
universe@221: If you want another name, you can configure the JNDI resource in the
universe@221: WEB-INF/web.xml and META-INF/context.xml files. It is highly recommended to use
universe@221: the lightpit_app user which has less privileges to create the data source and
universe@221: leave the lightpit_dbo user for the database operator.
universe@221: 
universe@262: 4. Build and Deploy the WAR file of lightpit
universe@221: 
universe@262: Build the WAR file with gradle. If your application server already provides
universe@262: the necessary runtime libraries for JSTL and PostgreSQL, leave the variable
universe@262: libsAreProvided = true during the build. Otherwise, set this variable to false
universe@262: and the libraries will be included in the WAR file. But keep in mind that some
universe@262: servlet containers, like Tomcat, are not so happy about this when hot redeploy-
universe@262: ments are performed. If you experience ClassDefNotFound errors after a hot
universe@262: redeployment, you should either provide the libs in your container or always
universe@262: restart the entire container after a redeployment.
universe@221: 
universe@254: 5. Configuring a web server and authentication
universe@221: 
universe@221: LightPIT can optionally detect the authenticated user. You may freely decide
universe@221: whether to enable authentication in your application server or put a web server
universe@221: in front. The latter is recommended, but keep in might that forwarding the
universe@221: authentication information may only work with AJP for certain servlet
universe@221: containers. Consult the respective manuals of the software you are using.
universe@221: 
universe@221: When the remote user is picked up successfully by LightPIT, comments under
universe@221: issues e.g. are personalized. For this to work the authenticated username must
universe@221: match one of the configured usernames in LightPIT.
universe@221: 
universe@221: Have fun!