Hand/custom install

You may want to install Twproject by hand because of your network or server settings, or because you are using an operating system without the graphic interface.
There are two ways to complete the installation: copying an existing one (easier) or doing it completely by hand (much complex).

 

Copying a graphical installation

If possible, do the graphical installation on a client machine that can access the database server, so that the installer can configure for your db access, license, http port and the other settings; doing all this by hand can be not trivial; then copy on the server. This is the simplest way.

Manual installation covers different cases : one is that you have already a web server running and a Java 1.8 JDK installed, and you want to add Twproject as a web app. The simplest way is to install using the installer on a client machine, with access to real database, as the installer will:

  1. create the database tables
  2. fill sample data
  3. create a global.properties file with SMTP and similar settings
  4. create a config.properties with the JDBC connection parameters
  5. create a lic.properties file with the license data supplied

As all the files created are fine on any O.S., just copy the resulting webapp from webapps/ROOT in the webapp folder for Twproject. Otherwise you will need to create all these by hand. A sample complete global.properties can be found as

webapps/ROOT/commons/settings/sampleGlobal.properties

Complete installation by hand

We assume that you have Java’s JDK 8 already installed, and also a Tomcat (9 or higher) running. If you don’t, download and install those first.

We are assuming that you are not deploying as an unpacked war, as the web app needs to write in its folders, so you must use a “unpacked” war.

  • Download and extract the archive version (zip, gz, or rpm)
  • Take the folder Twproject, it contains subfolders:

applications commons mobile WEB-INF

plus a few root files. This is the web app you need to install. Now:

  • Copy the web application inside your Tomcat webapps, in a folder with the name you please, say “twproject”. You must ensure that it is using JDK 8.
  • In WEB-INF/config.properties you must write the JDBC connection data and other configurations, several example configs:

MySQL 8 + :

user=root   
password=[yourpassword]    
url=jdbc:mySql://localhost/twproject
dialect=org.hibernate.dialect.MySQL8InnoDBUTF8Dialect
driver=com.mysql.cj.jdbc.Driver

MySQL 5.6.24 + :

user=root   
password=[yourpassword]    
url=jdbc:mySql://localhost/twproject
dialect=org.hibernate.dialect.MySQL57InnoDBUTF8Dialect
driver=com.mysql.cj.jdbc.Driver

MySQL 5.6.23 and before:

user=root   
password=[yourpassword]    
url=jdbc:mySql://localhost/twproject
dialect=org.hibernate.dialect.MySQL5InnoDBUTF8Dialect   
driver=com.mysql.cj.jdbc.Driver

SQLServer 2012+  mixed authentication:

user=sa
password=[yourpassword]    
url=jdbc:sqlserver://myserver:1433;databaseName=twproject
dialect=org.hibernate.dialect.SQLServer2012UnicodeDialect
driver=com.microsoft.sqlserver.jdbc.SQLServerDriver

#if it is an instance:
url=jdbc:sqlserver://myserver\\your_instance_name;databaseName=twproject

SQLServer 2008 mixed authentication:

user=sa
password=[yourpassword]    
url=jdbc:jtds:sqlserver://myserver:1433/twproject
dialect=org.hibernate.dialect.SQLServer2008UnicodeDialect
driver=net.sourceforge.jtds.jdbc.Driver

#if it is an instance:
url=jdbc:jtds:sqlserver://myserver:1433/twproject;instance=yourinstance

for the complete list of SQL Server options see http://jtds.sourceforge.net/faq.html

Oracle 12+:

schemaName=tw52setup
user=tw52setup
password=[yourpassword]    
url=jdbc:oracle:thin:@oldb02:1521:XE[ put your SID]    
dialect=org.hibernate.dialect.Oracle12cDialect   
driver=oracle.jdbc.driver.OracleDriver

Oracle 10+:

schemaName=tw52setup
user=tw52setup
password=[yourpassword]    
url=jdbc:oracle:thin:@oldb02:1521:XE[ put your SID]    
dialect=org.hibernate.dialect.Oracle10gDialectDBText   
driver=oracle.jdbc.driver.OracleDriver

PostgreSQL 9+:

user=postgres
password=[yourpassword]    
url=jdbc:postgresql://localhost/twproject
dialect=org.hibernate.dialect.PostgreSQLDialectMultiSequence9
driver=org.postgresql.Driver

PostgreSQL 8:

user=postgres
password=[yourpassword]    
url=jdbc:postgresql://localhost/twproject
dialect=org.hibernate.dialect.PostgreSQLDialectDBBlobs
driver=org.postgresql.Driver

For other databases / versions, please submit a ticket for updated connection strings. Again, actually the simplest way to be sure about Java connecting to the database is to do a graphical installation from a client and check the resulting config.properties file from there.

  • In WEB-INF you must also create a file lic.properties file in which you paste the evaluation license, for example
    ----- BEGIN TWPROJECT KEY -----
    PUbyP5tbmgGoAYQK3PIjcBhWOgdv7SDFM31bIV+LJZx/5xD2c7YGH0TzOByF/3Bc
    ewmde/QL6nmQEa0vx9xfcHTYacNoXfEDul8l1gCvqbM15vEH/YpiNDlGi+WPb7IN
    uH8XtbCBW3buXWS3Ctre4PxsPYf+bRE+m6cI8+CRROPI1M80f/G6sqKt0w9jhgBJ
    Y88EZ2puHlGeiojEhrQtd3fHN1As7bx9snMWZvD9/XvBRrYLQ7x47Egekz564NVT
    O6c2LCsndeY5Xz9WsJFg0tfJVTUfwd8MkWd/+BbRMjRUGvZk0Q4iGvf6qFpBpVrS
    PG6tFUI1HOWV13qgistINQ==
    ----- END TWPROJECT KEY -----
    

Note: this is not a valid license, generate it here: https://twproject.com/on-your-server/

  • This done, you may launch the web app; if you did the deploy operations while Tomcat was running, you may need to restart the web app. If the JDBC configuration is correct (this is most frequent mistake), the application will start, create the tables and insert sample data.
  • DEBUG If the web application “started too soon”, and say the insertion of sample data failed, open Commons/settings/global.properties remove the lines
SETUP_DB_UPDATE_DONE=yes

And restart the web app.

  • Remember to set the repository, file storage, indexing etc . paths in the admin pages.

If you are deploying under JBoss, take care of the Hibernate (including Annotations and Search) version you are using, Twproject provides its own, and it must be the same.