WebProtégé 3.0.0 Installation

This page describes how to install WebProtege 3.0.0. Please note that these instructions are for system administrators/managers that want to configure a local installation of WebProtege. We prefer that you use the Stanford hosted version of WebProtege at http://webprotege.stanford.edu, however, we realize that this is not possible in all cases and so we make WebProtege available for local installations. The instructions that follow assume familiarity with basic system admin tasks such as creating directories, setting file permissions etc.

Contents

• Prerequisites
• Installation Instructions
  • Set up the necessary directories for WebProtege
    • Create the WebProtege data directory
    • Create the WebProtege config directory
    • Create the WebProtege logs directory
  • Install and Setup WebProtege
    • Install the WebProtege WebApp
    • Bootstrap WebProtege with an Admin Account
    • Edit the WebProtege Settings

Prerequisites

WebProtege is a Java WebApp. The following software components need to be installed to run WebProtege:

• Java 8.
• Tomcat, or some other servlet container. In the setup instructions that follow, we refer to "Tomcat" as the servlet container. We require Tomcat 7, or higher.
• MongoDB.

You can find installation and setup instructions for these components at their respective websites by following the links above. You need to make sure that the MongoDB database server is running prior to performing the setup below.

Important: You should make sure that your servlet container is running in a JVM with the file encoding set to UTF-8. This should be specified as a command line argument when starting the servlet container i.e. -Dfile.encoding=UTF-8.

Installation Instructions

Set up the necessary directories for WebProtege

Create the WebProtege data directory

WebProtege requires a directory, that we call the data directory to store its data in. This data directory must exist prior to starting WebProtege. You can create the data directory anywhere on your system that is readable/writeable by Tomcat. By default, WebProtege expects the data directory to be /srv/webprotege. It is important that the data directory has the appropriate permissions so that Tomcat can read from it and write to it.

1. Create the data directory on your system. We recommend you use the standard location, /srv/webprotege. On a Windows system this corresponds to C:\srv\webprotege.
2. Ensure that the data directory that you've created has the appropriate permissions so that Tomcat can read from the directory and write to the directory.

Important: If you have an existing WebProtege 2.x installation you will need to migrate the data that is stored by WebProtege to the new backend format. To do this you should follow the WebProtege 2.x migration instructions before going any futher.

Create the WebProtege config directory

WebProtege has two configuration files:

• webprotege.properties. This file contains critical settings such as the path to the data directory and database connection information.
• mail.properties. This file contains mail server settings that WebProtege will use for sending out email notifications to users.

By default, both of these configuration files are embedded in the WebProtege war file (in the WEB-INF/classes directory) and will be read from there. However, we strongly recommend that you make copies of these files and adjust the various configuration properties as necessary for your installation. To do this, follow the steps below:

1. Create the directory to hold the WebProtege configuration files. On Linux/Unix/MacOS this should be /etc/webprotege. On Windows this should be C:\ProgramData\WebProtege (note that the ProgramData directory is a hidden directory).

2. Ensure that this directory has the appropriate permissions so that it can be read by Tomcat.

3. Create a copy of the webprotege.properties file inside this configuration directory.

4. In the webprotege.properties file you should adjust the various properties as appropriate for your installation. In particular, you should ensure that the data.directory property is set to point to the WebProtege data directory for your installation. For example, on Linux/Unix/MacOS,

   data.directory=/srv/webprotege

   or on Windows,

   data.directory=C:\\srv\\webprotege

   Note that the default value for the data directory property is /srv/webprotege on Linux/Unix/MacOS and C:\srv\webprotege on Windows. If you created the data directory in this location then you do not need to change this property.

5. Ensure that the webprotege.properties file can be read by Tomcat.

6. Create a copy of the mail.properties file inside the configuration directory that you created. You can copy the contents of the default mail.properties file and modify the various properties as appropriate for your installation. The mail.properties file supports the standard SMTP email configuration properties used by Java.

7. Ensure that the mail.properties file can be read Tomcat.

Create the WebProtege logs directory

WebProtege writes various information to various log files when it is running. The default location for these log files is the directory /var/log/webprotege on Linux/Unix/MacOS and C:\ProgramData\WebProtege\Logs on Windows. You should therefore create the appropriate directory for your platform and ensure that Tomcat can write to it.

1. Create the directory /var/log/webprotege if you are using Linux/Unix/MacOS or C:\ProgramData\WebProtege\Logs if you are using Windows.
2. Ensure that the logs directory has the appropriate permissions so that Tomcat can write to it.

Install and Setup WebProtege

Install the WebProtege WebApp

1. Make sure that Tomcat is stopped.
2. Remove any previous WebProtege installations: In the Tomcat webapps directory, delete any existing webprotege.war file and any existing webprotege directory.
3. Download the WebProtege 3.0.0 war file.
4. Rename the downloaded war file to webprotege.war
5. Copy the webprotege.war file to the tomcat webapps directory. You must ensure that the webprotege.war file has the appropriate permissions so that it can be read by Tomcat. Important: You MUST not have more than one version of WebProtege installed in the webapps directory.
6. Start Tomcat.
7. Ensure that WebProtege is running by opening a Web browser and navigating to the WebProtege home page. If your server is accessed at https://my.server.address and Tomcat is running on port 8080, then the WebProtege home page will be located at https://my.server.address:8080/webprotege. If there are any problems with missing directories or file permissions then an error page will be displayed. Otherwise the login page for WebProtege will be displayed.

Bootstrap WebProtege with an Admin Account

1. Download the WebProtege Command Line Tool.

2. In a terminal, set the working directory to the location of the webprotege-cli.jar file that you just downloaded.

3. Enter the following command into the terminal:

   java -jar webprotege-cli.jar create-admin-account

4. Follow the setup tool instructions in the terminal. You will be asked to provide a user name and password for the admin account. You need this user name and password later on, so remember these details!

Edit the WebProtege Settings

1. Open a web browser and enter the URL for the WebProtege home page into the browser. For example, assuming that your server is accessed at https://my.server.address and Tomcat is running on port 8080, the URL of the WebProtege home page is:

   https://my.server.address:8080/webprotege

2. # using the admin account that you created as part of the setup above.

3. Once you have signed in, navigate to the admin page at the URL obtained by appending #admin to the URL of the WebProtege home page. For example,

   https://my.server.address:8080/webprotege#admin

4. On the Main Settings tab, specify an email address where critical system notifications can be sent to in the System notification email address field.

5. On the Main Settings tab, specify the various URL components of the URL that is used to access your WebProtege installation. These details are used to compose user facing URLs in email notifications that WebProtege sends out to users. The URL components should therefore reflect the public URL of your WebProtege installation.

   1. Specify the scheme users use to access your WebProtege installation (either http or https).
   2. Specify the host name that users use to access your WebProtege installation (e.g. my.server.address)
   3. Specify the port that users use to access your WebProtege installation (e.g. 8080). Note that the port number is optional.
   4. Specify the path that users use to access WebProtege (e.g. /webprotege). Note that the path is optional.

6. On the Global Permissions tab,

   1. Specify whether you want account creation enabled.
   2. Specify whether you want project creation enabled.
   3. Specify whether you want project upload enabled and optionally specify a max file size.
   4. Specify whether you want email notifications enabled.

   Note that if you disable account creation users will not be able to create their own accounts. If you choose to do this then you will need to first enable account creation so that you can create accounts for them and then disable it thereafter.