Read Me

--------------------------------------------------
LaBB-CAT
--------------------------------------------------

For version information, check version.txt

To build and install the web application directly from the repository:

1. ensure you've installed Apache ant and node/npm
2. check the code out into a subdirectory of your Tomcat webapps directory
   - e.g. /var/lib/tomcat9/webapps/labbcat
3. edit WEB-INF/classes/config.xml, setting the value of the <tomcat/> tag appropriately
   for your system. 
4. cd WEB-INF/classes
5. ant install_webapp

Then use your browser to visit the webapp e.g. http://localhost:8080/labbcat

TO CREATE AN INSTALLABLE .WAR FILE:
--------------------------------------------------
2. cd WEB-INF/classes
3. ant war

The .war file is created in the <tomcat-install>/webapps/dist folder

TO CREATE AN UPGRADE FOR AN EXISTING INSTALL:
--------------------------------------------------
2. cd WEB-INF/classes
3. ant upgrade

A .jar file is created in the <tomcat-install>/webapps/upgrade folder, which can
be unzipped over an existing webapp install.  It is a self-extracting jar file, so
double-clicking it (or passing it to the java command with the -jar option) will unzip all
its contents to the current directory. 

MYSQL ROOT PASSWORD
--------------------------------------------------

When you browse to http://serverhostname:8080/labbcat/ the first time, you are presented with
an HTML form asking for various pieces of information required for completing the
installation. 

One piece of information you need is the password for MySQL's 'root' user. However, on some
distributions of Linux, you are not prompted to define a root password during the MySQL
installation process, and as a result there is no root password.

In this case, you must connect to MySQL using the mysql command-line tool, and manually create
the labbcat database and login credentials. To do this:

1. At the shell prompt, enter:
   sudo mysql
   This should start a mysql command prompt.
2. Enter:
   CREATE DATABASE labbcat CHARACTER SET utf8mb4;
3. Enter:
   CREATE USER 'labbcat'@'localhost' IDENTIFIED BY '<some password>';
4. Enter:
   GRANT ALL PRIVILEGES ON labbcat.* TO 'labbcat'@'localhost';
5. Enter:
   exit
6. Now, in the HTML form, tick the checkbox labelled:
   "The above database already exists, so don't create it."
7. Enter the <some password> you used above into the "Password" box.
8. Click the "install" button to continue with the installation process.

Problems/questions? Email robert.fromont@canterbury.ac.nz

TO INSTALL WITH USERNAME/PASSWORD SECURITY:
--------------------------------------------------
1. unzip war file to webapps
2. install webapp via the browser, remembering the MySQL details you use during the installation
3. edit web.xml to uncomment the security-constraint and login-config tags that are
   commented-out there 
4. copy mysql-connector-java-latest.jar from labbcat's WEB-INF/lib directory into Tomcat's
   lib directory, if it's not already there 
   - e.g. on Ubuntu:
     sudo ln -s /var/lib/tomcat9/webapps/labbcat/WEB-INF/lib/mysql-connector-java-latest.jar /usr/share/tomcat9/lib/
   - e.g. on Windows, copy mysql-connector-java-latest.jar
     from D:\Tomcat 9.0\webapps\{mylabbcat}\WEB-INF\lib
     to D:\Tomcat 9.0\lib
5. restart tomcat
6. login to labbcat via your browser, using the username: labbcat and the password: labbcat
7. change labbcat password by clicking the "[labbcat]" link in the top left of the menu
8. click the "users" menu option
9. add a user to the list
10. click the 'security' button next to the newly created user
11. set the user's password and click the 'change password' button
12. set the roles you want the user to have and click the 'save rols' button
13. repeat 10-14 for each of the users you want to add

TO USE LDAP AUTHENTICATION FOR USERNAMES/PASSWORDS
--------------------------------------------------
1. edit META-INF/context.xml to add CombinedRealm tag to the Context tag for your webapp,
that includes a Realm for LDAP 
       <Context ...>
         <Realm className="org.apache.catalina.realm.CombinedRealm" >
           <Realm
              className="org.apache.catalina.realm.JNDIRealm"
              connectionURL="ldap://{myldaphost}:3268"
              userBase="{myldapuserbase}"
              userSubtree="true"
              userSearch="{myldapusersearch}"
              userRoleName="memberOf"
              connectionName="{myldapconnectioncn}"
              connectionPassword="{myldapconnectionpassword}"
              />
           <Realm
              className="org.apache.catalina.realm.JDBCRealm" debug="99"
	      [...all the details of the MySQL Realm that was there before]
               />
         </Realm>
       </Context>
2. edit web.xml to add auth-constraint below the "view" one that's there already:
     <auth-constraint><role-name>view</role-name></auth-constraint>
     <auth-constraint><role-name>{myldapgroupname}</role-name></auth-constraint>
3. restart tomcat
4. login to labbcat as 'labbcat' (or some other admin user)
5. click 'users'
6. add an LDAP user
7. click 'security' for the new users
8. tick desired roles and click 'save roles'
9. repeat 5-8 for each of the LDAP users you require

After this, any LDAP users that:
 a) log in with the correct username and password, and
 b) are in the nominated LDAP group, and
 c) have the 'Search/View Transcripts' role ticked
... will be given access.

If you want to allow LDAP users that are in the LDAP group but are not explicitly set up
under 'users' in labbcat: 
10. in labbcat, click 'system attributes'
11. next to Enforce View Permission, select 'false'
12. click 'Save'

After this, LDAP users not explicitly mentioned on the 'users' page will be given view-only access.

TO RUN IN DOCKER CONTAINERS:
--------------------------------------------------

There is a Docker image you can use in the Docker Hub, called nzilbb/labbcat

https://hub.docker.com/repository/docker/nzilbb/labbcat

If you want to create it from this source code instead of using the publishe image:

1. Execute:
   cd install
2. Execute:
   docker build -t nzilbb/labbcat .
3. Execute:
   docker run --name=labbcat-db -e MYSQL_ROOT_PASSWORD=secret -e MYSQL_ROOT_HOST=% -d mysql/mysql-server:5.6 --character-set-server=utf8mb4 --collation-server=utf8mb4_general_ci
4. Execute:
   docker run --name=labbcat --link labbcat-db -d -p 8888:8080 nzilbb/labbcat
5. Visit:
   http://localhost:8888/

To build the Docker image for release:

1. Execute:
   cd install
2. Execute:
   docker build -t nzilbb/labbcat .
3. Find the current version:
   cat ../version.txt
4. Tag the build with the version number:
   docker tag nzilbb/labbcat nzilbb/labbcat:{version-from-version.txt}
5. Execute:
   docker push nzilbb/labbcat:{version-from-version.txt}
6. Execute:
   docker push nzilbb/labbcat

GENERAL CODE STRUCTURE:
--------------------------------------------------
jsx/...                 React components for certain parts of the UX.
WEB-INF/classes/...	Compiled servlet and API classes.
mvc/...			Dynamically compiled JSP scripts

The files in the "mvc" directory are generally the JSP scripts that generate
models and views for HTTP requests. For any given URL, there is usually:
 * a <URL>.jsp 	- which does the required processing, and often creates a model
     object which is added to the request attributes (the attribute is
     called "model"
 * a series of <URL>.<format>.jsp scripts - which generate views of the model,
     depending on the content type required.
 * a series of <URL>.help.jsp page - which represents that page's online help in HTML.

e.g. for the URL http://tld/labbcat/results:
 * mvc/results.jsp generates a model
 * mvc/results.html.jsp generates a "text/html" representation of the model
 * mvc/results.plain.jsp generates a "text/plain" representation of the model
 * mvc/results.csv.jsp generates a "text/csv" representation of the model
 * mvc/results.json.jsp generates a "application/json" representation of the model
 * mvc/results.help.jsp is the online help link for that page

Many pages rely on an Annotation Graph API called nzilbb.ag.  The source code for that API
is here:
https://github.com/nzilbb/ag

*NB* The LaBB-CAT codebase is currently in the process of rewriting and migration. This
 repository contains the legacy code. 

The new code is here:
https://github.com/nzilbb/labbcat-server

The code is build into a jar file which is included in this repository
(WEB-INF/lib/nzilbb.labbcat.server.jar)