The IPT stores configuration, resources, users and logs in its data directory. This can be set during installation, or the first time the IPT is run.
A typical location on Linux is
/var/lib/ipt (installed from packages) or
/srv/ipt (running in Tomcat). On Windows,
C:\ipt-data is appropriate. The IPT must have write permission to the chosen location.
Do not select a data directory that is vulnerable to inadvertent changes or removal. Do not use
The data directory should be backed up regularly in keeping with an appropriate disaster recovery plan.
Loss of the contents of the data directory will result in the loss of resource, user, and other configuration information and customizations to the IPT installation.
|If you have a data directory from a previously running IPT of the same version and want to use that previous configuration (including users and resources), you can enter the absolute path of that data directory below, or during the first step of the IPT setup.|
There are several ways to install the IPT.
Users of Red Hat, CentOS, Debian, Ubuntu or similar may install directly from Linux packages. This is the simplest method for the typical installation of a single IPT on a single server, and is also the easiest method to keep updated.
Other Linux users, all MS Windows users, and those who wish to run multiple IPTs on the same server should instead look at the section on Installation within a servlet container.
Docker images are also available, see Installation using Docker.
To install the IPT onto Red Hat 7, CentOS 7 or similar, first add the GBIF package repository and install the IPT package:
yum-config-manager --add-repo https://packages.gbif.org/gbif.repo yum install ipt
/etc/sysconfig/ipt to change the default data directory and port. Finally:
systemctl enable ipt systemctl start ipt
The IPT starts up on port 8080 (unless this was changed above). Initial logs are visible with
journalctl -u ipt, but are then logged in the data directory. Make sure to back up the IPT data directory, which is
/var/lib/ipt by default.
Successful installation of the IPT packages will make the IPT accessible through a web browser at a URL determined by the server’s name and port (e.g., http://server.example.org:8080). If the installation was successful, the initial IPT setup page will appear in a web browser using the IPT’s URL.
Installing the IPT within a servlet container consists of deploying the IPT
.war file in a servlet container such as Tomcat.
This section explains how to install different types of servlet containers on your server, and how to deploy the IPT within them.
It isn’t necessary to use an reverse proxy, but in case you do, the following section explains how to configure an Apache HTTPD virtual host declaration for the IPT.
The most common servlet containers used to deploy the IPT are Tomcat, Jetty and Wildfly8 (JBoss).
The IPT has been tested and works well with Tomcat 7, 8 or 9. The Apache Tomcat documentation can be found on http://tomcat.apache.org/.
Configure the IPT data directory within Tomcat
This step is optional, but is recommended to improve security and simplify the upgrade procedure.
Locate the Tomcat configuration directory (usually
C:\Program Files\Apache Software Foundation\Tomcat X.Y\confon Windows), and create a file
Catalina/localhost/ipt.xml(described in the Tomcat documentation "Defining a context"). For example, on a typical CentOS Linux installation, the file would be
IPT_DATA_DIRparameter within the file — copy and paste the text here, since the case of the letters is important:
<Context> <Parameter name="IPT_DATA_DIR" value="/srv/ipt"/> </Context>
If this step is not done, the IPT will prompt for a data directory when it is first run. The location will be stored in a file called
datadir.locationthe IPT’s base installation directory, e.g.
If the data directory location needs to be changed, remove/edit this file and restart Tomcat.
Deploy the IPT
Download the latest WAR release of the IPT from the releases page and rename it to
ipt.war(or similar, matching
ipt.xmlfrom step 2 if used). Copy the
ipt.warfile to the Tomcat webapps folder, and then start Tomcat if it is not already running. You can then invoke the IPT in a web browser running on the same server by using the following URL: http://localhost:8080/ipt
If the installation doesn’t start please check the
catalina.outlogfile, and refer to the FAQ for help.
Successful deployment of the IPT within a servlet container will make the IPT accessible through a web browser at a URL determined by the servlet’s name and port, followed by /ipt (e.g., http://server.example.org:8080/ipt). If the installation was successful, the initial IPT setup page will appear in a web browser using the IPT’s URL.
The following screencast also explains how to install the IPT using Tomcat, assuming Tomcat has already been installed.
Multiple IPTs can be installed on the same server with a small variation to this process. Rather than (or in addition to) using
As a very rough guide, on CentOS, to run a single instance of the IPT:
yum install jetty-runner java -jar /usr/share/java/jetty/jetty-runner.jar --port 8080 ipt.war
GBIF maintain a Docker image, published to the Docker Hub. The image builds upon the Docker community Tomcat 8.5 / OpenJDK 8 / Debian stable image. Tomcat is exposed on port 8080 and the IPT runs as the ROOT application.
To run a new Docker container, startup Tomcat and expose the Tomcat port run like this:
docker run --detach --volume /full/path/to/data-directory:/srv/ipt --publish 8080:8080 gbif/ipt
You can then access the setup screen of the IPT on port 8080.
If you need to override the data directory, this can be done with
If you need to find the IP address of your "default" Docker machine use
docker-machine ip default.
Run a specific version from those available by using
gbif/ipt:version rather than
You will probably need to work with your system or network administrator for the IPT to be available on the Internet.
You will need a DNS name for the server (“ipt.example.org”) and the firewall to allow access.
Many people use Apache HTTPD as a reverse proxy, often to provide HTTPS access or to allow sharing other websites on the same server.
The configuration used by
ipt.gbif.org is shown here as an example. It uses Apache HTTPD, with the
mod_proxy module installed. The paths
/icons are excluded from being passed to the IPT, to allow hosting static image files (such as occurrence images) on the same server. Requests to http://ipt.gbif.org/ are redirected to the secure https://ipt.gbif.org/.
<VirtualHost *:80> ServerName ipt.gbif.org CustomLog logs/ipt-80_log combined Redirect / https://ipt.gbif.org/ </VirtualHost> <VirtualHost *:443> ServerName ipt.gbif.org ErrorLog logs/ipt-443_error CustomLog logs/ipt-443_log combined DocumentRoot /var/www/html/ipt Options +Indexes AddDefaultCharset UTF-8 ProxyPreserveHost On ProxyPass /favicon.ico ! ProxyPass /icons ! ProxyPass /media ! # Linux packages example ProxyPass / http://localhost:8080/ ProxyPassReverse / http://localhost:8080/ # Example for an IPT deployed in a servlet container like Tomcat #ProxyPass / http://localhost:8080/ipt/ #ProxyPassReverse / http://localhost:8080/ipt/ #ProxyPassReverseCookiePath /ipt / RequestHeader set X-Forwarded-Proto "https" # Typical LetsEncrypt configuration SSLCertificateKeyFile /etc/letsencrypt/live/ipt.gbif.org/privkey.pem SSLCertificateFile /etc/letsencrypt/live/ipt.gbif.org/fullchain.pem Include /etc/letsencrypt/options-ssl-apache.conf </VirtualHost>
For production deployments of the IPT we recommend using a TLS certificate, so information such as logins are secured when accessing the IPT. The procedure to set this up sometimes depends on your institution’s policies, but the free LetsEncrypt service is a good choice. They provide instructions for adding a certificate to Apache, Nginx and many other webservers running on Linux or Windows.
For a new deployment, it is best to set up the webserver with TLS first, then install and set up the IPT. Adding a certificate to a configured IPT requires changing the public URL. See the note on updating the public URL in the administration section.