Setup
In this section, we will explain how to get Germinate up and running. There are several different ways to achieve this. Depending on your expertise and requirements, you can choose the option that suits you best. Building from source requires basic knowledge of the command line.
We try to keep the requirements of Germinate as basic as possible. In order to run Germinate you will need to have the following applications available on your server:
- Apache Tomcat (>=8.0.47) to run the web application
- Java (>=8) to run Apache Tomcat and the Germinate server side code
- MySQL (>=5.7.17 and <8) or MariaDB (>=10.2.7) database to hold the data
Please make sure that you have the required applications installed before continuing.
Germinate and Gatekeeper have their own separate databases. Each one needs to be set up before being able to use Germinate. We provide a simple SQL script that takes an empty database and sets up all the tables and views that Germinate requires. This script is included in the database subfolder in the source code of Germinate and Gatekeeper (cf. Section "Downloading the source code"). Simply run this script against the empty Germinate and Gatekeeper databases respectively.
Building Germinate from source is the most flexible way of getting Germinate up and running. It allows you to make use of all of Germinate's customization options and tailor it specifically to your needs.
In addition to the basic requirements, you will need Apache Ant (1.9.1 or above) to be installed on the system you are building Germinate on.
We host the Germinate and Gatekeeper code on GitHub since version 3.4.0. They are available here:
https://github.com/germinateplatform/
To download the code, please use your favourite Git client and create a clone of the latest release of Germinate and Gatekeeper respectively.
Before you start configuring your instance of Germinate, take a copy of the folder instance-stuff/template into the folder instance-stuff/<your germinate instance>. This folder and its contents are explained in Section "Structure".
Both applications contain a file called build.xml which is the Apache Ant build script as well as an associated build.template.properties file. These files are used to compile and deploy the application. Rename the build.template.properties file to build.properties. Edit the build.properties file and replace the placeholder username and password with your Apache Tomcat username and password. Replace the placeholder for your web server as well.
# Ant properties for building the GWT app
project.name=germinate-templace
project.root=jhi.germinate.Germinate
instance.files=./instance-stuff/<your germinate instance>
tomcat.manager.url=http://<Your web server>:8080/manager/text
tomcat.manager.username=<Username>
tomcat.manager.password=<Password>The next file that needs editing is the config.properties file. In the case of Gatekeeper this file is located in the root directory. In the case of Germinate, you can find this file in the instance-stuff/<your germinate instance> folder.
Configure Gatekeeper in the following way:
database.server=<server holding germinate>
database.name=<database name>
database.useport=<is a port necessary?>
database.port=<port number>
database.username=<username, e.g. germinate3>
database.password=<password>
[...]Finally, configure Germinate in the following way:
Germinate.Database.Server=<server holding germinate>
Germinate.Database.Name=<database name>
Germinate.Database.Port=<port number>
Germinate.Database.Username=<username, e.g. germinate3>
Germinate.Database.Password=<password>
Gatekeeper.URL=<base url of gatekeeper>
Gatekeeper.Database.Name=<name of gatekeeper database>
Gatekeeper.Database.Server=<server holding gatekeeper>
Gatekeeper.Database.Port=<port number>
[...]To build the application, simply run ant from the command line in the root directory of Germinate and Gatekeeper. Apache Ant will then run the build script and compile the source code and finally deploy it to your Apache Tomcat installation.
Make sure that the machine you're compiling the source on can communicate with the web server via HTTP (required to deploy the application).
After the build finishes successfully, you should be able to view Germinate in your browser. The address is based on your configuration. It should have this structure: http://Your web server:8080/project.name.
Section "Building Germinate from source") walked you through the process of building Germinate from source. If you would like to automate a low of the steps involved in this process, you can try and run the Germinate installation script. This script runs on Linux and is meant to be used when you are working with Germinate for the first time. It will take care of all the steps from downloading the source, setting up the database to building and deploying the source code.
Detailed information about the script are available on our website at:
https://ics.hutton.ac.uk/germinate/download-germinate/
In case you have been provided with compiled versions of Germinate and Gatekeeper in the form of a .war file each as well as their database counterparts in your MySQL installation, then all you need to do is deploy them to Tomcat.
To deploy these applications, navigate to the following URL:
http://Your web server:8080
You should see something similar to the figure above. Click on the button labelled "Manager App" and you will be prompted to enter your credentials. Use the username and password defined in the file tomcat-users.xml. The following page will show all the applications running on Tomcat right now. Below this table, there is a section called "Deploy" with subsection "WAR file to deploy". Simply select each of the two WAR files by clicking on the "Browse" button and then click on "Deploy". Germinate and Gatekeeper should now be listed in the applications table at the top of the page.
Clicking on the Path link in the first column of the overview table should redirect you to Germinate and Gatekeeper respectively.
The first time you go to the Gatekeeper website, you'll see the form shown in the figure above. Fill it in to create the initial admin account. After this, you will be able to log in to Gatekeeper and create other users, database systems and set their permissions.
Depending on your configuration (ref. Germinate.Server.Logging.Enabled in Section Configuration), Germinate will log all server-side exceptions. This can be useful when you need to debug your version of Germinate.
The log files are stored to this location: <Tomcat Directory>/temp/logs/. Each instance of Germinate uses its own log files to avoid mix-ups.