TaniaTudorache: Created page with "{{WP1-start}}
WebProtégé 1.0 Administrator's Guide
TOC '''Go back to [[WebP..."

2013-04-25T20:30:18Z

Created page with "{{WP1-start}} <p style="padding:0; margin:0; font-size:1.9em; font-weight:bold; word-spacing:-2px;">WebProtégé 1.0 Administrator's Guide</p> __TOC__ '''Go back to [[WebP..."

New page

{{WP1-start}}

<p style="padding:0; margin:0; font-size:1.9em; font-weight:bold; word-spacing:-2px;">WebProtégé 1.0 Administrator's Guide</p>

__TOC__

'''Go back to [[WebProtege|WebProtégé main page]].'''

''' Find [[MigrateOntologiesFromWP1|here]] instructions on how to move your ontology to the new WebProtege server (http://webprotege.stanford.edu) '''

= Introduction =

''' This page describes the administration and installation for the WebProtege 1.0 (that works with Protege 3.x series). '''

WebProtégé is a web application that runs in a [http://en.wikipedia.org/wiki/Servlet_container#Servlet_containers servlet container], such as [http://tomcat.apache.org/ Tomcat]. WebProtégé comes as a ''war file'' that can be easily deployed in a servlet container.

There are two ways to install and run WebProtégé:
# '''Local Mode''': WebProtégé loads the ontologies from a standalone instance of Protégé running in a servlet container (''default mode''), or
# '''External Server Mode''': WebProtégé loads the ontologies from a Protégé server running outside of the servlet container, and acts as a web-based client connecting to the Protégé server (see more information about the client-server version of Protégé [[Protege_Client-Server_Tutorial|here]]). This WebProtégé mode of operation is also sometimes called the ''client-server mode''.

= WebProtégé WAR file =
The WebProtégé WAR file is available for download from here:

[http://wp-obs.stanford.edu/downloads/wp-r1.0/webprotege_r1.0.war.zip WebProtege 1.0]

Unzip the file to get the war file. If you are using the external server mode mode of WebProtégé, then please check the Protégé - WebProtégé compatibility table from below and make sure that the Protégé server and WebProtégé are compatible.

= Install WebProtégé - Local mode =

In ''Local Mode'', WebProtégé loads the ontologies from a standalone instance of Protégé running in a servlet container, such as Tomcat. WebProtégé will '''NOT''' use the Protégé server to manage ontology loading. The ''Local Mode'' is the default mode of operation for WebProtégé.

== Deploy the WebProtégé WAR file ==

Deploy the WebProtégé WAR file into your Servlet container. The procedure for doing this will be specific to which Servlet container you are using. At [[Stanford_Center_for_Biomedical_Informatics_Research|BMIR]], we are currently using the latest version of [http://tomcat.apache.org/download-55.cgi Tomcat 5.5]. If you are also using Tomcat, you can use the following steps to deploy:

<ul>
<li>Start Tomcat</li>
<li>Copy webprotege.war into the webapps folder</li>
</ul>

Tomcat will unpack the WAR file and the exploded file structure should look something like the following:

<div style="padding-top:5px; padding-bottom:5px;">
[[Image:Webprotege-in-tomcat.jpg|thumb|600px|none|WebProtégé deployed in Tomcat]]
</div>

Next, you can optionally configure the metaproject, or proceed to the [[#Test the WebProtégé installation|section on testing your installation]].

== Configure the metaproject ==

By default, WebProtégé will display a list of example ontologies that are available for the user to edit on the ''My WebProtégé'' page. If you want to edit
the list of available ontologies, you need to edit the metaproject. The metaproject is a frame-based ontology that models permissions and controls which projects are displayed to the user, as well as which users have access to which projects. A more [[Protege_Client_Server_Tutorial_Configuration#The_Metaproject|detailed explanation of the metaproject]] is available in the Protégé Client-Server Tutorial.

Please note that this step is optional and only needs to be performed when you want users to have access to ontologies other than the examples provided with the default installation.

To edit the metaproject, launch the Protégé application and open metaproject.pprj, located in <your-servlet-container>/webprotege/projects/metaproject.

Any time you make edits to the metaproject, you must restart your Servlet container for WebProtégé to detect changes.

If you decided to make changes to the metaproject, please restart your Servlet container and then proceed to the [[#Test the WebProtégé installation|section on testing your installation]].

= Install WebProtégé - External Server Mode =

In ''External Server Mode'', WebProtégé loads the ontologies from a Protégé server running outside of the servlet container, and acts as a web-based client connecting to the Protégé server (see more information about the server/client version of Protégé [[Protege_Client-Server_Tutorial|here]]).

Other clients, such as [[Collaborative_Protege|Collaborative Protégé]] can connect to the same Protégé server, and browse and edit the same ontology. All edits made in either client will immediately be seen in the other clients.

== Protégé Standalone Application ==

'''You need to download the Protégé standalone application only if you decide to use the External Server Mode!'''

If you are using the ''External Server Mode'', WebProtégé loads the ontologies from the Protégé server. If you want to run WebProtégé with the Protégé server, you need to install a version of the standalone [http://protege.stanford.edu/overview/ Protégé application]. If you are unfamiliar with the Protégé server and would like to learn more, a [[Protege_Client-Server_Tutorial|detailed tutorial is available]] on this wiki.

If you are a new user, [http://protege.stanford.edu/download/register.html please register] before downloading Protégé. For existing users, Protégé is [http://protege.stanford.edu/download/registered.html#p3 available on the download page] of the main Protégé website.

''Please make sure to download the proper compatible version of Protégé standalone:''

{| style="width:75%; margin-top:2px;" border="1" cellpadding="1" cellspacing="1"
!width="50"|Protégé standalone
!width="50"|WebProtégé
|+ '''Version dependency table for Protégé Standalone & WebProtégé'''
|- style="text-align:center;"
|[http://protege.stanford.edu/download/protege/3.5/installanywhere/Web_Installers/ Protégé 3.5 or newer release] ||
[http://wp-obs.stanford.edu/downloads/wp-r1.0/webprotege_r1.0.war.zip WebProtege 1.0]  (2013-Apr-25)
|- style="text-align:center;"
|[http://protege.stanford.edu/download/protege/3.4/installanywhere/Web_Installers/ Protégé 3.4.8 release] <br /> [http://protege.cim3.net/download/3.5/installanywhere/ Protégé 3.5 beta or newer release] ||
[http://protegewiki.stanford.edu/images/3/34/WebProtege_2012.09.19.war.zip WebProtege 1.0 RC1]  (2012-Sept-19)
|- style="text-align:center;"
|[http://protege.cim3.net/download/old-releases/3.4.6/installanywhere/Web_Installers/ Protégé 3.4.6 release] ||
[http://protegewiki.stanford.edu/images/2/21/Webprotege_2011.05.28.war.zip 0.5 beta, build 501]  (2011-May-28)<br />
[http://protegewiki.stanford.edu/images/9/97/Webprotege_2011.05.13.war.zip 0.5 beta, build 500]  (2011-May-13)
|- style="text-align:center;"
|[http://protege.cim3.net/download/old-releases/3.4.4/installer/ Protégé 3.4.4 release] ||
[http://protegewiki.stanford.edu/images/f/f2/Webprotege_2010.05.12.war.zip 0.5 alpha, build 300]  (2010-May-12)
|- style="text-align:center;"
|[http://protege.cim3.net/download/old-releases/3.4.1/full/ Protégé 3.4.1 release] ||
[http://protege.stanford.edu/download/webprotege/0.5/webprotege.war 0.5 alpha, build 200]  (2009-Aug-14)<br />
[http://protege.stanford.edu/download/webprotege/0.5/webprotege-0.5.103.war 0.5 alpha, build 103]  (2009-Aug-01)
|- style="text-align:center;"
|[http://protege.cim3.net/download/old-releases/3.4/full/ Protégé 3.4 release] ||
[http://protege.stanford.edu/download/webprotege/0.5/webprotege-0.5.102.war 0.5 alpha, build 102]  (2009-Apr-03)
|- style="text-align:center;"
|[http://protege.cim3.net/download/old-releases/3.4%20betas/build-513/full/ Protégé 3.4 beta, build 513] || [http://protege.stanford.edu/download/webprotege/0.5/webprotege-0.5.101.war 0.5 alpha, build 101]  (2008-Oct-25)
|}

== Configure the Protégé server's metaproject ==

The Protégé server controls the list of projects that users see in WebProtégé. It also controls which users have access to which projects. Administrators can modify this information in the "metaproject", which is a frame-based ontology that models permissions. A more [[Protege_Client_Server_Tutorial_Configuration#The_Metaproject|detailed explanation of the metaproject]] is available in the Protégé Client-Server Tutorial.

Launch Protégé and open the metaproject.pprj file located in the examples/server directory. Please note that you must use a version of the Protégé application that is compatible with the build of WebProtégé you are using. There is a version dependency table at the top of this guide.

Select the '''User''' class in the Class Hierarchy and click the Create Instance button in the Instance Browser pane to create a new user. Fill in "webprotege" as the Name and Password for this user. This user is used internally by WebProtégé when communicating with the Protégé server. To follow is a screenshot of the metaproject after this edit:

<div style="padding-top:5px; padding-bottom:5px;">
[[Image:Webprotege-configure-metaproject.jpg|thumb|600px|none|Metaproject after addition of "webprotege" user]]
</div>

At this point, you can also add new users and/or delete any example users that come with the default installation of Protégé. You can also click on the '''Project''' class to configure the list of projects that will be available to users of WebProtégé. Please note that the '''Location''' property for projects should be relative the the directory where the Protégé server is running (the root directory of your Protégé installation).

''Don't forget to save your changes to the metaproject before continuing with the next steps.''

== Start the Protégé server ==

WebProtégé requires an instance of the Protégé server to be running. Detailed instructions for starting the server are [[Protege_Client-Server_Tutorial#Starting_and_Testing_the_Server|provided in the Protégé Client-Server Tutorial]].

There is a known issue with Java 1.6.0_29 and Java 1.7 related to starting the Protégé server. Read more [[Troubleshooting_Client_Server_Connections#Java_1.6.0_29_and_1.7_rmiregistry_issue|here]].

== Deploy the WebProtégé WAR file ==

Deploy the WebProtégé WAR file into your Servlet container. The procedure for doing this will be specific to which Servlet container you are using. At [[Stanford_Center_for_Biomedical_Informatics_Research|BMIR]], we are currently using the latest version of [http://tomcat.apache.org/download-55.cgi Tomcat 5.5]. If you are also using Tomcat, you can use the following steps to deploy:

<ul>
<li>Start Tomcat</li>
<li>Copy webprotege.war into the webapps folder</li>
</ul>

Tomcat will unpack the WAR file and the exploded file structure should look like the following:

<div style="padding-top:5px; padding-bottom:5px;">
[[Image:Webprotege-in-tomcat.jpg|thumb|600px|none|WebProtégé deployed in Tomcat]]
</div>

== Edit the protege.properties file ==

Open the protege.properties file, located in <your-servlet-container>/webprotege. Edit the following property by changing the value from false to true:

<pre>load.ontologies.from.protege.server=true</pre>

Save your changes and restart your Servlet container.

== Configure the Collaborative Protégé JNLP file (optional) ==
If you are running WebProtégé in the ''External Server Mode'', users may launch a Protégé desktop client using [http://java.sun.com/javase/technologies/desktop/javawebstart/index.jsp Java Web Start technology]. This means that users can browse and edit the same ontology both in a desktop application and in a web browser. Changes made in either client (desktop or WebProtégé) will immediately be seen by the other clients.

In order for this functionality to work properly, it is necessary to edit the collabProtege_OWL.jnlp file in the root directory of the WebProtégé application. Edit the codebase attribute in the JNLP file to match the base URL of WebProtégé on your server:

<pre><jnlp spec="1.5+" codebase="http://localhost:8080/webprotege" href="collabProtege_OWL.jnlp"></pre>

If a user launches a Protégé client, they are presented with a dialog that requires them to enter the host machine name:

<div style="padding-top:5px; padding-bottom:5px;">
[[Image:Connect-remote-host-dialog.jpg|none]]
</div>

It is easier for users if the host machine name is auto-filled. This can be configured by uncommenting the argument element in application-desc and filling in your host machine name. An example is provided in the default installation:

<pre>
<application-desc main-class="edu.stanford.smi.protege.Application">

<argument>-propui.welcomedialog.start.in.server.panel=true</argument>
<argument>-propserver.client.preload.skip=true</argument>
<argument>-propedu.stanford.smi.protege.server.ServerPanel.user_name=Your_user_name_here</argument>
</application-desc>
</pre>

= Test the WebProtégé installation =

After you have completed all of the installation steps, launch a Web browser and enter the following URL:

<pre>http://your-host-name[:your-optional-port-name]/webprotege/WebProtege.html</pre>

If you have successfully installed WebProtégé, you will see the '''My WebProtégé''' tab with the list of available ontologies for users to edit:

<div style="padding-top:5px; padding-bottom:5px;">
[[Image:Webprotege-install-success.jpg|none|frame|A successful install of WebProtégé !!]]
</div>

= WebProtégé configuration =

== Configuring projects, users and access policies ==

In both running modes (local and external server), you may configure the projects loaded into WebProtégé (the ones shown in the ''My WebProtégé'' tab), the users and their groups, and the access policies for each project. These configurations are made in the ''metaproject'' file.

We have very detailed instructions on how to configure the metaproject in this [[Protege_Client_Server_Tutorial_Configuration|user guide]].

In '''Local Mode''', the ''metaproject'' is located by default in ''<your-servlet-container>/webapps/webprotege/projects/metaproject''. In '''External Server Mode''', the metaproject is located by default in the Protégé installation directory where you started the Protégé server/''examples/server'' subfolder.

The '''access policies''' currently enforced in WebProtégé are the ''Read'',''Write'' and ''DisplayInProjectsList'' policies.

'''Note'''. If you run WebProtégé in the ''External Server Mode'', the metaproject from '<your-servlet-container>/webapps/webprotege/projects/metaproject'' has no function. This metaproject is only used if you run in ''Local Mode''. The metaproject used by the ''External Server Mode'' is the one used by the Protégé server.

== Configuring the WebProtégé operation ==

You may configure other parameters of the WebProtégé operation by editing the ''protege.properties'' from the ''<your-servlet-container>/webapps/webprotege/war'' folder.

Below is a list of supported properties.

<pre>
# Set to true to use WebProtégé in external server (client-server) mode; default false
load.ontologies.from.protege.server=true

# In local mode, you may specify an alternative location for the metaproject
local.metaproject.path=/tmp/metaproject.pprj

# Hostname of the Protégé server to be used if WebProtégé runs in external server (client-server) mode. It can also contain a port number
server.hostname=localhost

# User name that WebProtégé uses to connect to the Protégé server, if WebProtégé runs in external server (client-server) mode
webprotege.user=webprotege

# Password that WebProtégé uses to connect to the Protégé server, if WebProtégé runs in external server (client-server) mode
webprotege.password=webprotege

# Automatic save interval for the projects, if WebProtégé runs in local mode (recommended to use database backend)
server.save.interval.sec=120
</pre>

== Configuring the user interface layout ==

All the layout in WebProtégé is configurable: all the tabs, the layout of the tabs, portlets, etc. can be configured, so that WebProtégé can be customized for different projects.

The layout configuration is described on this [[WebProtegeLayoutConfig|page]].

== Run WebProtege over https ==

To run WebProtege over https there are a few easy configurations that need to be done, which are documented on [[WebProtegeHttpsLogin|this page]].

= Troubleshooting =

== Always look first at the log files ==

WebProtégé tries to help you by writing out log messages when something goes wrong. If you report a problem on the mailing list, please make sure that you also include the log files, otherwise it is hard for us to help.

'''Location of log files''':

* ''Servlet container'': Check the documentation of your servlet container to get the log files location. In Tomcat, the logs are in the ''<tomcat_install_folder>''/logs/catalina.out
* ''Protégé server'': If you are running WebProtégé in External Server Mode, then the Protégé server will print out messages in the console where you have started the Protégé server using the run_protege_server script. Always look there first. The Protégé server log files are located in the folder where you started the Protégé server in the ''logs'' subfolder.

When start WebProtégé, you should see a message printed in the servlet container log file (catalina.out in Tomcat):

'''Local mode''':
<pre>
WebProtégé running in: /usr/share/tomcat5.5/webapps/web-protege/web-protege/war/
Path to local metaproject: /usr/share/tomcat5.5/webapps/web-protege/war/projects/metaproject/metaproject.pprj
WebProtégé server running with local projects
</pre>

'''External server mode''':
<pre>
WebProtégé running in: /usr/share/tomcat5.5/webapps/web-protege/web-protege/war/
WebProtégé server running with remote projects loaded from the Protégé server: localhost
</pre>

== Troubleshooting the Local Mode ==

'''1. No ontologies are showing up in ''My WebProtégé'' tab'''

If this is a default configuration, then the metaproject used to configure the projects is located in: ''<your-servlet-container>/webapps/webprotege/projects/metaproject''.

Check the servlet container log (e.g., catalina.out) to see where the metaproject is loaded from (see above). If you have changed the default location of the local metaproject in the protege.properties file, then make sure that the file exist and is loaded from that location. If it is not found, you will see an error log message.

Check the access policies in the metaproject. If you are not logged into WebProtégé, the projects shown in the ''My WebProtégé'' tab are the ones that the group ''World'' has access to. Make sure that the group ''World'' has the ''Read'' and ''DisplayInProjectList'' access policies attached to the projects you want to see by default in ''My WebProtégé'' tab.

Restart the servlet container to see the changes.

'''2. Cannot open project error, or project is empty '''

This usually happens when the path of a project in the metaproject is wrong. Check the servlet container log. You will see something like:

<pre>
Loading project Pizza from file:/work/src/GWT/web-protege/web-protege/war/projects/pizza_does_not_exist/pizza.owl.pprj
SEVERE: Unable to load project from: file:/work/src/GWT/web-protege/web-protege/war/projects/pizza_does_not_exist/pizza.owl.pprj -- Project.getProjectInstancesReader()
WARNING: There were errors at loading project Pizza Errors: [edu.stanford.smi.protege.util.MessageError@300a3c] -- ProjectManager.openProjectLocal()
</pre>

Fix the path of the project in the metaproject, restart WebProtégé and the servlet container, and try again.

== Troubleshooting the External Server Mode ==

'''1. Cannot not start the Protégé server'''

Please refer to the [[Troubleshooting_Client_Server_Connections|troubleshooting section]] of the client-server Protégé.

'''2. No ontologies are showing up in ''My WebProtégé'' tab'''

Check the servlet container and the Protégé server logs for error messages.

Check the access policies in the metaproject. If you are not logged into WebProtégé, the projects shown in the ''My WebProtégé'' tab are the ones that the group ''World'' has access to. Make sure that the group ''World'' has the ''Read'' and ''DisplayInProjectList'' access policies attached to the projects you want to see by default in ''My WebProtégé'' tab.

Restart the Protégé server and the servlet container to see the changes.

'''3. You get a message in a window saying that "Load project XYZ failed." '''

Please check the following things in this order:

* Check the servlet container and the Protégé server logs for error messages.
* Check that the Protégé server is still running. Look in the Protégé server log for exceptions. You may see some of the following messages:

<pre>
WARNING: Missing project at examples/newspaper/newspaper.pprj -- Server.getAvailableProjectNames()
</pre>

This means that the project path is misconfigured in the metaproject. Fix the path and restart the Protégé server and the servlet container to see the changes.

<pre>
WARNING: Failed to open project: Session(id=3, user=webprotege) tried to open project Collaborative Pizza, but project is closed for maintenance -- Server.openProject()
</pre>

This means that the project is closed for maintainance. To check and change the status of a project on the Protégé server, you can use the [[Protege_Client_Server_Tutorial_Administration|Server Admin application]]

<pre>
java.lang.OutOfMemoryError: Java heap space
</pre>

This means that the Protégé server has run out of memory. You need to increase the heap size available to the Protégé server in the <code>run_protege_server</code> script. Edit the line that contains the <code>-Xmx500M</code> and increase the amount of memory. We have some recommendations about setting the heap size [[Setting_Heap_Size|here]]. It is also not recommended that you use a file backend on the Protégé server, but rather use a database backend, that decreases the amount of memory needed and it is much safer in the case the Protégé server or the machine crashes. More information about this [[Protege_Client_Server_Tutorial_Setup#Which_type_of_back-end_to_use_.28database_vs._file-based.29_in_client-server_mode|here]].

In any of these cases, '''restart the Protégé server and the servlet container to see the changes'''.

You may see other exceptions in the log, which should give you an idea what went wrong. '''If you report a problem on the Protégé mailing lists, make sure to include the logs in your post'''.

* If you do not see any exceptions in the logs, then start a Protégé desktop client and connect to the Protege server that is also used by WebProtégé. Instructions on how to connect a Protégé client to a Protégé server are available [[Protege_Client_Server_Tutorial_Setup#Testing:_Connect_a_Client_to_the_Server|here]]. Try to log in with the WebProtégé user and password (default user name: webprotege, password: webprotege). If you cannot log in, it means that you have forgot to create a user and password ''webprotege'' in the metaproject. (This only applies for the case in which you run WebProtégé in External Server Mode).

Another thing that might go wrong is that the Protégé jars used by WebProtégé and the Protégé server versions are not the same. Please look on this wiki page in the ''Install'' section for the table of correspondence between the WebProtégé release and the Protégé serve versionr. Make sure that you are running compatible Protégé server and WebProtégé versions.

'''4. Cannot log in WebProtégé'''

Probably you are trying to connect with the wrong user/password combination. To test this, start a Protégé desktop client and connect to the Protégé server that is also used by WebProtégé. Instructions on how to connect a Protégé client to a Protégé server are available [[Protege_Client_Server_Tutorial_Setup#Testing:_Connect_a_Client_to_the_Server|here]]. Try to log in with the user name and password that you tried in WebProtégé. If you do not succeed, then check the Protégé server metaproject, to check the valid user/password combination. If you do succeed, then check the Protégé server logs and the servlet container logs for any other error messages.

== Where to get more help ==

If you have trouble installing WebProtégé, please send email to the [https://mailman.stanford.edu/mailman/listinfo/webprotege-feedback WebProtege 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 [http://protege.stanford.edu/doc/faq.html Mailing Lists section] of our FAQ.

'''Go back to [[WebProtege|WebProtégé main page]].'''

[[Category:WebProtege documentation]]

← Older revision		Revision as of 01:13, April 26, 2013
Line 359:		Line 359:
	'''Go back to [[WebProtege\|WebProtégé main page]].'''		'''Go back to [[WebProtege\|WebProtégé main page]].'''

−	[[Category:WebProtege documentation]]	+	[[Category:WebProtege 1.0 documentation]]

WebProtege1.0AdminGuide - Revision history

TaniaTudorache at 01:13, April 26, 2013

TaniaTudorache: Created page with "{{WP1-start}}
WebProtégé 1.0 Administrator's Guide
TOC '''Go back to [[WebP..."

WebProtege1.0AdminGuide - Revision history

TaniaTudorache at 01:13, April 26, 2013

TaniaTudorache: Created page with "{{WP1-start}} WebProtégé 1.0 Administrator's Guide __TOC__ '''Go back to [[WebP..."

TaniaTudorache: Created page with "{{WP1-start}}
WebProtégé 1.0 Administrator's Guide
TOC '''Go back to [[WebP..."