From Protege Wiki

Jump to: navigation, search

WebProtégé Administrator's Guide


Go back to WebProtégé main page.

The wiki page for the old WebProtege (release 1.0) can be found here.


This page describes the administration and installation for the latest WebProtege (the one available on http://webprotege.stanford.edu).

WebProtégé is a web application that runs in a servlet container, such as Tomcat. WebProtégé comes as a war file that can be easily deployed in a servlet container.

Download the latest WebProtégé build from GitHub.

Note: The latest build is marked with a green tag "Latest release". Scroll down the release notes, and click the button to download the corresponding webprotege zip file.


All you need is:

  • Tomcat (or some other servlet container)
  • mongoDB - used to store different WebProtege configuration data
  • webprotege.war file
  • and a data directory where WebProtege will store all its data.

Install Tomcat

Visit the Tomcat page for downloading and installation instructions. Tomcat has a webapps folder in which you should copy the webprotege.war file. You may also use other servlet engines, instead of Tomcat.

Install mongoDB

WebProtege uses mongoDB to store various configuration. We may use it in the future to store also other types of data. WebProtege will not start, if mongoDB is not installed.

Follow the mongoDB installation instructions for your operating system. The installation is easy, and usually requires no or very little configuration.

As part of the installation process, you may be required to create a folder where mongoDB will keep its data (e.g., on Windows, default location is c:\data\db, Linux: /data/db), and give access to the mongodb user to that folder. The mongoDB website has easy-to-follow, step-by-step installation instructions for all operating systems.

Ideally, mongoDB should run as a service. If that is not possible, you need to make sure to start it manually, as explained in the installation website.

For your information,the mongoDB default host is localhost and the default port is 27017.

Download webprotege.war

You can download a zip file containing the webprotege.war file from GitHub.

The archive name will usually contain a date and a build number. Unzip the file to get the webprotege.war file.

Create a data directory

WebProtege stores all of its data (ontologies, project configurations, change history, etc.) in a data directory. Please create a data directory outside of your webapp folder (so that updates will be easy later). This directory needs to exist prior to starting WebProtege, and the user that runs tomcat (or your servlet container), needs to be able to write to this folder.

For example, on Linux or OSX, you may create a data directory /data/webprotege, by typing in a console:

 mkdir /data/webprotege
 chown tomcat /data/webprotege

Note. In the chown command, if tomcat is running under a different user name, just replace tomcat with the correct user name. You may need to use sudo in front of the commands.

For example, on Windows, you can create a directory C:\data\webprotege by typing in a Command Prompt:

  md data
  md data\webprotege

You can use any directory on your filesystem, as long as the tomcat user can write to it.

Deploying WebProtege

Deployment is easy, just copy the webprotege.war into the webapps folder of your servlet container. If using tomcat, copy webprotege.war into tomcat_install_dir/webapps/.

There are two main configuration properties that WebProtege needs in order to run:

  • data.directory - this is the data directory where WebProtege keeps all of its data and you created in the previous step
  • application.host - this is the URL under which WebProtege is deployed, without the http part. For example: application.host=webprotege.stanford.edu

There are three ways to configure the two required properties for WebProtege (just pick the one that is easier for you).

  • (1) Set them as Java arguments using the '-D' option when starting your servlet container. For example, on Linux and OSX, if you are using tomcat, you can edit the catalina.sh and add this line (adapt to your own paths):
JAVA_OPTS="$JAVA_OPTS -Dwebprotege.data.directory=/data/webprotege -Dwebprotege.application.host=webprotege.stanford.edu"

Please note that the property names are prefixed with webprotege. On Windows systems, edit the catalina.bat.

- or -

  • (2) Set them as environment variables. Check your operating system documentation on how to set environment variables. For example,

- or -

  • (3) Set them in the webprotege.properties file that is available under webprotege webapps folder. This file can be used to store other properties as well. Documentation on all the properties is available here. If the webprotege.properties file does not exist in your expanded webprotege folder in tomcat/webapps, just create one, or copy the one under etc/webprotege.properties.template and rename it to webprotege.properties.

For example, your webprotege.properties could look like (Linux example):


Please note that the property names are not prefixed by 'webprotege.', as in the first two cases.

For Windows systems, the data directory path needs to use the Windows separator, so it will look like:


File Encoding

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

Testing the installation

Once you have deployed the webprotege.war file, you are ready to start WebProtege. Just start your servlet engine (e.g., for tomcat on Linux, you can type in a console sudo service tomcat6 start), and in a browser, go to the URL where you deployed it. In most cases, you can test the deployment on localhost; just open a Web browser and go to:


and you should see WebProtege with no ontologies:


If you don't see this screen, you probably see an error message that will tell you how to fix the problem. (For example, you forgot to set the two required properties, or the data directory is not writable by the tomcat user).

Once you have successfully installed WebProtege, you can start by creating an account for you (click on the Sign Up for Account button), and then after signing in, you can upload ontologies (by clicking on the Create Project or Upload Project button), and then share it with your collaborators (via the Share button). Please read more about the features of WebProtege and how to use them in the WebProtege User Guide.

Configuration and Customization (optional)

Configuring email

WebProtege can be configured to send email for change notifications using SMTP.

Starting with WebProtege build 112, the email can be configured in 2 ways:

1. Create a file mail.properties in the root of the the web application (same level as webprotege.properties), and add any property as defined in the Java SMPT package and its value, e.g.,



2. The mail properties can be defined as Java arguments when starting the servlet container (e.g., tomcat), same way as the webprotege.properties were defined, e.g.:

    JAVA_OPTS="$JAVA_OPTS -Dmail.smtp.host=mySmtpServer.myOrganization.org"

In addition to the properties defined in the Java SMPT package, you can also use two more properties:

    mail.smtp.wp.password - the SMTP password, if you are using authentication
    mail.smtp.from.wp.personalName - the "From" name from which the email will be sent. The default is the value of the application.name property (set via webprotege.properties, and whose default value is WebProtege)

Depending on your setup, you should consider setting the following properties (see the Java documentation): mail.smtp.host; if using authentication: mail.smtp.auth=true, mail.smtp.user, mail.smtp.wp.password.

User interface customization

If you would like to customize the layout and content of the WebProtege user interface, please read the instruction on this page.

Updating WebProtege

The update of WebProtege should be fairly easy and painless. Just replace the webprotege.war file from your tomcat webapps folder with the newer version of this file. Since all the data is stored outside of the webapps folder, you don't need to worry about that. If you have created the webprotege.properties and mail.properties in the root of the web-app (rather than using the Java arguments method), make sure that you preserve these two files when you upgrade WebProtege.


If you have problems at install or deployment, WebProtege will try to help you by giving the error messages and fix suggestions in the browser.

If you don't see any fix suggestions, or they don't work, please consult the log files of your servlet container. For example, in Tomcat, the logs are in the <tomcat_install_folder>/logs/catalina.out and <tomcat_install_folder>/logs/localhost_yyyy-mm-dd.log

Please include these logs when writing on the mailing list to report a problem, otherwise it is very hard for us to help.

Where to get more help

If you have trouble installing WebProtégé, please send email to the protege-user mailing list.

It is difficult for us to help in the absence of error messages. Please check the log files for your Servlet container and include the text of any exceptions written out.

If you are unsure how to subscribe to our mailing lists, please see the Mailing Lists section of our FAQ.

Go back to WebProtégé main page.

Personal tools