Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
documentation [2020/01/27 19:17]
webadmin [Installation]
documentation [2020/01/27 23:39]
webadmin [Prerequisites]
Line 169: Line 169:
  
  
-Hosting of the Wildbook Framework requires installation of a web server and several software dependencies. It is recommended that you have some experience with web applications and command line interface ​in UNIX or Mac+Hosting of the Wildbook ​Mark-Recapture ​Framework requires installation of a web server and several software dependencies. It is recommended that you have some experience with web applications, git version control ​and the Linux command line interface. ​ 
 + 
 +Wildbook software does not come with computer vision identification automatically deployed. New species and unique datasets require new trained machine learning models and setup. Please contact us at [[services@wildme.org]] to inquire about these options.  
 + 
 +** You can [[ https://​www.wildbook.org/​doku.php?​id=downloads | clone the Wildbook repository]] from Github to build and deploy using this guide. ** 
  
  
 ==== Prerequisites ==== ==== Prerequisites ====
  
 +We run Wildbook on Microsoft Azure hosted Ubuntu Linux 18.04 servers. It is possible to follow these same instructions and host the software locally on your computer. There have been widely varying degrees of success hosting Wildbook on Macintosh, and no known running instances on Windows. Our support for installations on non Linux operating systems must be limited to the Wildbook software itself and not hosting or setup.
 + 
 +Many of the dependencies below have simple Ubuntu command line installations easily found via a web search and it is recommended to look for the latest command and use it. 
  
-To run the frameworkyou will need a Linux server (recommended) with the  following software pre-installed:​+To run the framework you must have the following software pre-installed:​
  
 +    * **[[http://​www.oracle.com/​technetwork/​java/​index.html|Java SE 8]]** (a.k.a, "Java 1.8") or later LTS release. Wild me uses Java 11. This are available from [[https://​openjdk.java.net/​install/​|OpenJDK]] or  [[http://​www.oracle.com/​technetwork/​java/​index.html|Oracle]] .  If you have other Java versions set up, ensure that your system is pointing to Java 8 or later for the JAVA_HOME environment variable.
  
-    ​* **[[http://www.oracle.com/technetwork/java/index.html|Java SE 8]]** (a.k.a, "Java 1.8"). This are available ​from [[http://​www.oracle.com/​technetwork/​java/​index.html|Oracle]] or [[http://​openjdk.java.net/​projects/​jdk8/​|OpenJDK]]. At a minimumdownload ​and install the Java Runtime Environment (JRE); if you wish to develop Java programs, download and install ​the Java Development Kit (JDK), which includes ​the JREDon't forget to define JAVA_HOME as a system environment variable (settings its value to the file system path to Java on your computer) to allow Java-based applications to use your installed Java version. +  ​* **[[https://linuxize.com/post/how-to-install-apache-maven-on-ubuntu-18-04/ | Apache Maven]]** Maven is used to compile the Wildbook repository downloaded ​from GithubIt will generate the WAR file referenced later in these instructions, and wrap up any changes ​you make to the repository code into the deployable applicationIt is available ​through apt-get installation on updated Ubuntu systemsEnsure you have the required version ​of Java installed ​prior to installing Maven.
-    * **Tomcat Webserver, version 8 or greater**, ​ which is available ​from the [[http://​tomcat.apache.org/​download-70.cgi|Apache Software Foundation]]. Download the "​binary distribution"​ that is appropriate for your operating system (e.g., "​64-bit Windows zip" for 64-bit Windows machines, or "​zip"​ or "​tar.gz"​ for Linux and Macintosh machines). Tomcat is a "​servlet container"​ that can run Java-based applications under a web server. It can also act as a web server by itself. Jetty, older versions of  Tomcat, and other J2EE containers/​servers may work but have not been tested. Integration of Tomcat with third party web servers (e.g., Apache 2.2.x) is common, but this topic is well beyond ​the scope of these instructions. These sample instructions assume that Tomcat has been installed ​on your local laptop or desktop and is listening on port 8080.+
  
-    * [[http://​www.imagemagick.org/​script/​convert.php|ImageMagick]] - ImageMagick must be available from the command line for image manipulation. Specifically,​ we use the '​convert'​ command for image thumbnail generation but may use other commands in the future. +    * **Tomcat 8** We recommend Tomcat 8 or greaterTomcat 8.5 is available in updated Ubuntu servers via **apt-get** installation  Tomcat is also available from the [[http://tomcat.apache.org/​download-70.cgi|Apache Software Foundation]]. You can also download and install ​the "​binary distribution"​ that is appropriate for your operating system. Tomcat is a "​servlet container"​ that can run Java-based applications under a web server. ​It can also act as a web server ​by itself. Wild Me uses NGINX as web server and to manage HTTPS certifications ​with Tomcat 8.5 running underneath on running web deployments
-    * [[http://www.postgresql.org|PostgreSQL]] database installed on the server. ​Wildbook ​by default tries to connect to Postgres database on the same server ​named '​wildbook'​ on localhost:​5432 with username '​wildbook' ​and password '​wildbook'​ permissions. +
-    * sendmail - Wildbook can email data contributors and researchers ​with data updatesOn Linux servers, sendmail is required.+
  
-Technically,​ Wildbook can also be run on Windows and Mac laptops and desktops, but we highly recommend running Wildbook on an Ubuntu Linux virtual machine from Azure, which makes the server setup and management process very easy. If you need support, please contact ​[[mailto:services@wildbook.org|services@wildme.org]]. Be aware that we are happy to answer questions ​but cannot offer comprehensive instructions on Mac or Windows ​installation. +    * [[http://​www.imagemagick.org/​script/​convert.php|ImageMagick]] ImageMagick is available through apt-get installation on updated Ubuntu installations ​ImageMagick must be available from the command line for image manipulation. Specifically, ​we use the '​convert'​ command for image thumbnail generation ​but may use other commands in the future. ImageMagick is also available through apt-get ​installation ​on updated Ubuntu installations
-==== Installing Tomcat ====+
  
-Installing Tomcat ​is beyond ​the scope of this document, but it is very well documented ​on the web+    * [[http://​www.postgresql.org|PostgreSQL]] PostgreSQL ​is available on updated Ubuntu systems with an apt-get installation. Wildbook by default tries to connect to a Postgres database on the same server named '​wildbook' ​on localhost:​5432 with username '​wildbook'​ and password '​wildbook'​ permissions. You can (and should) change these in the *jdoconfig.properties* file found in the Wildbook repository. You will need to log in to PostgreSQL to create a database using the name, password and owning user you choose.
  
-**//We HIGHLY recommend running ​Wildbook ​on an Ubuntu ​Linux web server through Microsoft'​s ​Azure cloud//**.+    ​* **Postfix** - Wildbook ​can email data contributors and researchers with data updates using Postfix. This is available via an Ubuntu ​command line installation. **You will also need an outgoing SMTP service like mailjet** in order to send mail from an Azure server. The Mailjet/Postfix setup guide is found [[https://​app.mailjet.com/​docs/​code/​postfix|here]]. Your outgoing email address is customizable in the *commonConfiguration.propertiesfile found in the Wildbook repository, and will be required for the email setup process. Email setup can be tricky and varies based on deployment choices. This is the method Wild Me uses on our deployed platforms
  
-  * Tomcat is very well supported for Linux, but instructions for downloading and installing will vary according to Linux flavor. Consult your Linux distro (you may already have Tomcat) or the Web for Tomcat installation instructions for your Linux platform. + ​If ​you need supportplease contact ​[[mailto:support@wildbook.org|support@wildme.org]]Be aware that we are happy to answer questions but cannot offer much guidance on Mac or Windows installation. ​We recommend Microsoft Azure and Ubuntu Linux deploymentand support outside that is limited by experience 
-  * For Windows operating systemsTomcat can be [[http://tomcat.apache.org/​download-70.cgi|downloaded with Windows ​installers]],​ making the installation ​process very easy. +
-  * [[http://​wolfpaulus.com/​journal/​mac/​tomcat7|For Macintosh hardwarethese instructions are excellent]]. Use Apple'​s "​Terminal"​ app to type the various "​sudo"​ commands shown in the instructions.+
  
 +==== Tomcat Setup ====
  
 +Tomcat will deploy applications on port :8080, under the same name as the deployed application WAR file. You will need to configure the docBase of Tomcat to be the same name as the application file you deploy making it the default or '​root'​ application. This will allow you to point a web server or domain name at the application consistently. Methods of doing this can vary by Tomcat version so it is best to look for the instructions for your chosen version online.
  
-===Known good configurations=== 
  
-We run Wildbook exclusively on Ubuntu servers on Microsoft'​s Azure cloud. We use Java 8+ and Tomcat 8.  +==== Deploying the Application ​====
- +
-==== Deploying the WAR file ====+
  
 <​html>​ <​html>​
  
-Wildbook is downloaded and deployed as a web application archive file (.WAR) in Tomcat. To install this file+Wildbook is downloaded and deployed as a web application archive file (.WAR) in Tomcat. To generate a current WAR file, navigate to the root application directory of a Wildbook repository you have cloned ​from Github
-<​ol>​ +
-<​li>​Using your web browserdownload ​the latest available WAR file (wildbook.war) ​from <a href="​http://​www.wildbook.org/​doku.php?​id=downloads+
  
 +If you have successfully completed the above prerequisites,​ you will be able to build and deploy the version of your choice. Use that Maven command 'mvn clean install',​ to download application dependencies,​ compile the code and package it into the WAR file. The generated WAR file should be found in the repositories target/ folder.
  
- +Once the file is generated: 
- +<ol>
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
- +
-" target="​_blank">​the downloads page</a>.  +
 <​li>​Place the wildbook.war file in the "​webapps"​ folder of Tomcat. For example: <​li>​Place the wildbook.war file in the "​webapps"​ folder of Tomcat. For example:
 <​ul> ​ <​ul> ​
Line 289: Line 218:
 </ul> </ul>
  
-<​li>​Open a web browser to your server'​s URL or IP address ​plus "/​wildbook"​. A default landing page for Wildbook is displayed. This steps assumes a basic Tomcat installation on a web server with Tomcat assigned to use its default port 8080.+<​li>​Start or restart Tomcat to ensure application deployment. This can be done with a service or using included shell scripts depending on your Tomcat version and installation method. 
 + 
 +<​li>​Open a web browser to your server'​s URL or IP address ​port :8080. A default landing page for Wildbook is displayed. This steps assumes a basic Tomcat installation on a web server with Tomcat assigned to use its default port 8080.
  
-<​li>​Log into the framework using the default '​tomcat'​ user ID and '​tomcat123'​ password.+<​li>​Log into the framework using the default '​tomcat'​ user ID and '​tomcat123'​ password. This user is auto-generated if no other users are found in the database.
  
 </ol> </ol>
Line 300: Line 231:
  
 <​html>​ <​html>​
-Wildbook is now ready for use. Keep in mind that Tomcat must be running to enable access to Wildbook through your Web browser. If Tomcat is stopped, or your computer is rebooted, Tomcat must be restarted ​as described above.+Wildbook is now ready for use. Keep in mind that Tomcat must be running to enable access to Wildbook through your Web browser. If Tomcat is stopped, or your computer is rebooted, Tomcat must be restarted.
 </​html>​ </​html>​