WebProtegeAdminGuide
From Protege Wiki
WebProtege Administrator's Guide
Contents |
Introduction
WebProtege is a web application that runs in a servlet container, such as Tomcat. WebProtege comes as a war file that can be easily deployed in a servlet container.
There are two ways to install and run WebProtege:
- Local Mode: WebProtege loads the ontologies from a standalone instance of Protege running in a servlet container (default mode), or
- External Server Mode: WebProtege loads the ontologies from a Protege server running outside of the servlet container, and acts as a web-based client connecting to the Protege server (see more information about the client-server version of Protege here). This WebProtege mode of operation is also sometimes called the client-server mode.
WebProtege WAR file
The WebProtege alpha WAR file is available for download from the main Protege website:
http://protege.stanford.edu/download/webprotege/0.5/webprotege.war
Install WebProtege - Local mode
In Local Mode, WebProtege loads the ontologies from a standalone instance of Protege running in a servlet container, such as Tomcat. WebProtege will NOT use the Protege server to manage ontology loading. The Local Mode is the default mode of operation for WebProtege.
Deploy the WebProtege WAR file
Deploy the WebProtege WAR file into your Servlet container. The procedure for doing this will be specific to which Servlet container you are using. At BMIR, we are currently using the latest version of Tomcat 5.5. If you are also using Tomcat, you can use the following steps to deploy:
- Start Tomcat
- Copy webprotege.war into the webapps folder
Tomcat will unpack the WAR file and the exploded file structure should look something like the following:
Next, you can optionally configure the metaproject, or proceed to the section on testing your installation.
Configure the metaproject
By default, WebProtege will display a list of example ontologies that are available for the user to edit on the MyWebProtege 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 detailed explanation of the metaproject is available in the Protege 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 Protege 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 WebProtege to detect changes.
If you decided to make changes to the metaproject, please restart your Servlet container and then proceed to the section on testing your installation.
Install WebProtege - External Server Mode
In External Server Mode, WebProtege loads the ontologies from a Protege server running outside of the servlet container, and acts as a web-based client connecting to the Protege server (see more information about the server/client version of Protege here).
Other clients, such as Collaborative Protege can connect to the same Protege server, and browse and edit the same ontology. All edits made in either client will immediately be seen in the other clients.
Protege Standalone Application
You need to download the Protege standalone application only if you decide to use the External Server Mode!
If you are using the External Server Mode, WebProtege loads the ontologies from the Protege server. If you want to run WebProtege with the Protege server, you need to install a version of the standalone Protege application. If you are unfamiliar with the Protege server and would like to learn more, a detailed tutorial is available on this wiki.
If you are a new user, please register before downloading Protege. For existing users, Protege is available on the download page of the main Protege website.
Please make sure to download the proper compatible version of Protege standalone:
| Protege standalone | WebProtege |
|---|---|
| Protege 3.4.1 release |
0.5 alpha, build 200 (2009-Aug-14) |
| Protege 3.4.1 release |
0.5 alpha, build 103 (2009-Aug-01) |
| Protege 3.4 release |
0.5 alpha, build 102 (2009-Apr-03) |
| Protege 3.4 beta, build 513 | 0.5 alpha, build 101 (2008-Oct-25) |
Configure the Protege server's metaproject
The Protege server controls the list of projects that users see in WebProtege. 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 detailed explanation of the metaproject is available in the Protege Client-Server Tutorial.
Launch Protege and open the metaproject.pprj file located in the examples/server directory. Please note that you must use a version of the Protege application that is compatible with the build of WebProtege 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 WebProtege when communicating with the Protege server. To follow is a screenshot of the metaproject after this edit:
At this point, you can also add new users and/or delete any example users that come with the default installation of Protege. You can also click on the Project class to configure the list of projects that will be available to users of WebProtege. Please note that the Location property for projects should be relative the the directory where the Protege server is running (the root directory of your Protege installation).
Don't forget to save your changes to the metaproject before continuing with the next steps.
Start the Protege server
WebProtege requires an instance of the Protege server to be running. Detailed instructions for starting the server are provided in the Protege Client-Server Tutorial.
Deploy the WebProtege WAR file
Deploy the WebProtege WAR file into your Servlet container. The procedure for doing this will be specific to which Servlet container you are using. At BMIR, we are currently using the latest version of Tomcat 5.5. If you are also using Tomcat, you can use the following steps to deploy:
- Start Tomcat
- Copy webprotege.war into the webapps folder
Tomcat will unpack the WAR file and the exploded file structure should look like the following:
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:
load.ontologies.from.protege.server=true
Save your changes and restart your Servlet container.
Configure the Collaborative Protege JNLP file (optional)
If you are running WebProtege in the External Server Mode, users may launch a Protege desktop client using 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 WebProtege) 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 WebProtege application. Edit the codebase attribute in the JNLP file to match the base URL of WebProtege on your server:
<jnlp spec="1.5+" codebase="http://localhost:8080/webprotege" href="collabProtege_OWL.jnlp">
If a user launches a Protege client, they are presented with a dialog that requires them to enter the host machine name:
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:
<application-desc main-class="edu.stanford.smi.protege.Application"> <!-- <argument>-propedu.stanford.smi.protege.server.ServerPanel.host_name=bmir-protege-dev1.stanford.edu:5200</argument> --> <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>
Test the WebProtege installation
After you have completed all of the installation steps, launch a Web browser and enter the following URL:
http://your-host-name[:your-optional-port-name]/webprotege/WebProtege.html
If you have successfully installed WebProtege, you will see the My WebProtege tab with the list of available ontologies for users to edit:
WebProtege configuration
Configuring projects, users and access policies
In both running modes (local and external server), you may configure the projects loaded into WebProtege (the ones shown in the MyWebProtege 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 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 Protege installation directory where you started the Protege server/examples/server subfolder.
The access policies currently enforced in WebProtege are the Read,Write and DisplayInProjectsList policies.
Note. If you run WebProtege 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 Protege server.
Configuring the WebProtege operation
You may configure other parameters of the WebProtege operation by editing the protege.properties from the <your-servlet-container>/webapps/webprotege/war folder.
Below is a list of supported properties.
# Set to true to use WebProtege 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 Protege server to be used if WebProtege runs in external server (client-server) mode. It can also contain a port number server.hostname=localhost # User name that WebProtege uses to connect to the Protege server, if WebProtege runs in external server (client-server) mode webprotege.user=webprotege # Password that WebProtege uses to connect to the Protege server, if WebProtege runs in external server (client-server) mode webprotege.password=webprotege # Automatic save interval for the projects, if WebProtege runs in local mode (recommended to use database backend) server.save.interval.sec=120
Troubleshooting
Always look first at the log files
WebProtege 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
- Protege server: If you are running WebProtege in External Server Mode, then the Protege server will print out messages in the console where you have started the Protege server using the run_protege_server script. Always look there first. The Protege server log files are located in the folder where you started the Protege server in the logs subfolder.
When start WebProtege, you should see a message printed in the servlet container log file (catalina.out in Tomcat):
Local mode:
WebProtege 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 WebProtege server running with local projects
External server mode:
WebProtege running in: /usr/share/tomcat5.5/webapps/web-protege/web-protege/war/ WebProtege server running with remote projects loaded from the Protege server: localhost
Troubleshooting the Local Mode
1. No ontologies are showing up in MyWebProtege 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 WebProtege, the projects shown in the MyWebProtege 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 MyWebProtege 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:
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()
Fix the path of the project in the metaproject, restart WebProtege and the servlet container, and try again.
Troubleshooting the External Server Mode
1. Cannot not start the Protege server
Please refer to the troubleshooting section of the client-server Protege.
2. No ontologies are showing up in MyWebProtege tab
Check the servlet container and the Protege server logs for error messages.
Check the access policies in the metaproject. If you are not logged into WebProtege, the projects shown in the MyWebProtege 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 MyWebProtege tab.
Restart the Protege 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 Protege server logs for error messages.
- Check that the Protege server is still running. Look in the Protege server log for exceptions. You may see some of the following messages:
WARNING: Missing project at examples/newspaper/newspaper.pprj -- Server.getAvailableProjectNames()
This means that the project path is misconfigured in the metaproject. Fix the path and restart the Protege server and the servlet container to see the changes.
WARNING: Failed to open project: Session(id=3, user=webprotege) tried to open project Collaborative Pizza, but project is closed for maintenance -- Server.openProject()
This means that the project is closed for maintainance. To check and change the status of a project on the Protege server, you can use the Server Admin application
Restart the Protege 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 this problem on the Protege mailing lists, make sure to include the logs in your post.
- If you do not see any exceptions in the logs, then start a Protege desktop client and connect to the Protege server that is also used by WebProtege. Instructions on how to connect a Protege client to a Protege server are available here. Try to log in with the WebProtege 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 WebProtege in External Server Mode).
Another thing that might go wrong is that the protege jars used by WebProtege and the Protege server versions are not the same. Please look on this wiki page in the Install section for the table of correspondence between the WebProtege release and the Protege serve versionr. Make sure that you are running compatible Protege server and WebProtege versions.
4. Cannot log in WebProtege
Probably you are trying to connect with the wrong user/password combination. To test this, start a Protege desktop client and connect to the Protege server that is also used by WebProtege. Instructions on how to connect a Protege client to a Protege server are available here. Try to log in with the user name and password that you tried in WebProtege. If you do not succeed, then check the Protege server metaproject, to check the valid user/password combination. If you do succeed, then check the Protege server logs and the servlet container logs for any other error messages.
Where to get more help
If you have trouble installing WebProtege, please send email to the protege-discussion 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.
