Single User Installation
This installation guide details the process for installing Essential Open Source in the Stand-Alone mode.
External Dependencies
Essential Open Source has some external dependencies that are required before setting up Essential.
1. Java Runtime Environment
Before starting the installation of Essential Open Source, confirm whether or not a JVM has been installed. From a command prompt, type:
The resulting message from Java should show a JVM version at or above version 1.8.x. If a JVM is already present that meets the required version, there is no need to install the JVM that is provided with Protege.
If you do not already have a Java Runtime Environment installed, please download and install the correct JRE/JVM for your platform.
2. Install Protege
If you have not already installed Protege, install it by running the installation program.
2.1 Microsoft Windows
The following steps should be followed to install Protege on a Microsoft Windows Platform.
- Run the install_protege.exe file.
- Select the option to install "Everything" as this will include the optional tab widgets that may prove useful at a later date, e.g. Prompt, Jambalaya.
- Select the installation folder, preferably take the default in Program Files\Protege_x.x.x
- Select the JVM that Protege should use. If from Step 3, a suitable JVM (version 1.8 or above) has already been installed, select that JVM.
- Select 'Next' until the installation completes.
2.2 Other platforms - Mac OS X, Linux, Unix
Run the Protege installer for your platform and follow these steps:
- Select the option to install "Everything" as this will include the optional tab widgets that may prove useful at a later date, e.g. Prompt, Jambalaya.
- Select the installation folder, preferably take the default
- Select the JVM that Protege should use. If from Step 3, a suitable JVM (version 1.7 or above) has already been installed (this will be the case on Mac OS X), select that JVM.
- Select 'Next' until the installation completes.
2.3 Configure Protege
Please open Protege now.
- Go to the 'File' menu and select 'Preferences'.
- Un-select the option 'Sort class tree (Classes Tab)' to ensure that the Essential Meta Model class hierarchy is shown in the correct order.
- Click OK and exit Protege.
3. Apache Tomcat Java Application Server
If you do not already have Tomcat (or an alternative Java Application Server that can run Java Servlets) installed, please install it by running the installation program for your platform.
Like Protege, Tomcat requires Java v1.8 or above. For simplicity, select the same JVM that was selected during the Protege installation. In this case when prompted by the Tomcat installer, select the path to the folder "jre".
Core Components
Essential Open Source is comprised of four core components which must be installed separately.
Essential Widgets
Essential Widgets is a set of custom-built plug-ins for the Protege Ontology Editor.
1. Run Essential Widgets Installer
Having installed the pre-requisites, run the Essential Widgets installer, which will guide you through the rest of the installation process. The following sections in this guide provide additional detail about the options for the installer and the questions that it will ask.
To run the installer:
If, for some reason the installer is not recognised as an executable JAR file, use the following command at command prompt/terminal window:
(where xx is replaced by the version number as required)
You will now see the welcome panel of the installer and will be guided through the install process.
2. Important Information and License Agreement
The Information Panel provides important information about the installation and pre-requisites. Please read these before proceeding to the license agreement.
3. Select Essential Open Source Packages to Install
The Essential Open Source installer is divided into packages, enabling the installer to be used for installation possibilities.
For standalone installations, the 'Server' pack is optional but you can select all the install packages.
4. Specify Protege and Tomcat Locations
Essential Open Source includes plugins that must be installed into your Protege and Apache Tomcat (or alternative Java Web Application Server) installations.
The installer will ask you to specify the location of both your Protege and Apache Tomcat (or alternative Java Web Application Server). An attempt to automatically find Protege and Apache Tomcat in typical installation locations will be made. If the installer cannot find your Protege and Apache Tomcat installations, please use the 'Browse...' button to specify the folders in which they are installed.
If you have multiple versions of Protege installed, use the drop-down box or the 'Browse...' button to select which version of Protege that the Essential Widgets should be installed into.
When you select an location for either Protege, the installer will verify that location to ensure that you have selected a valid folder. Select the correct deployment location for Essential Viewer in your Web Application Server installation. For Apache Tomcat, select /webapps. For other Java Web Application Servers, please refer to your supplier's documentation for Web Application deployment to find the correct location for deploying the Essential Viewer WAR file.
5. Essential Open Source Server Configuration (Optional)
Even though this is a stand-alone installation, to aid future migrations to a server-based multi-user installation, you can choose to install the Server components of the installation.
If you are installing to a fresh installation of Protege, select the default option to install the server configuration directly into the Protege environment.
However, if you are installing Essential Open Source to a machine that already has Protege installed and running as a server in a multi-user environment, you should select an alternative location at this step of the installion, e.g. your Essential Repository location, to avoid the existing server configuration being over-written.
6. Finished
The installer will now install all the components of Essential Open Source to the locations that you have specified in the above steps.
When the installation has completed successfully, you can create an automated installer to repeat this installation configuration, e.g. to install another verbatim copy on another machine. Select the 'Generate an automated installation script' option and specify the name and location of your automated install script.
Essential Meta-Model
Both the meta-model and the model for Essential Open Source are contained in the repository which is controlled from a Protege project file, and has the file extension, .pprj
Download and save this to a user accessible area on your machine such as your Documents folder. Unzip and then open the resulting PPRJ file using Protege.
All changes to the model are stored in this file and we recommend you take regular backups of the file in the event you wish to revert the repository to an earilier state.
Essential Viewer
Essential Viewer is a Java Web Application for publishing, analysing and reporting against enterprise architecture models captured using the Essential Meta-Model.
- Download and save the latest Essential Viewer WAR file.
- Rename the file to "essential_viewer".
- Copy the renamed file to the "webapps" folder of your Tomcat installation folder.
Essential Import Utility
Essential Import Utility is a Java Web Application for importing existing content from spreadsheets into the Essential repository.
- Download and save the latest Essential Import Utility WAR file.
- Rename the file to "essential_import_utility".
- Copy the renamed file to the "webapps" folder of your Tomcat installation folder.
Start Tomcat
If it is not already running, please start Tomcat using the appropriate method for your operating system
Configure Memory Settings
Please check the memory settings are correctly configured for your set-up, see memory settingsο»Ώ
Installation Complete
Your stand-alone installation of Essential Open Source is now complete. Now go to the Getting Started Tutorials to find out more about capturing and analysing your architecture with Essential Open Source.
The Essential Baseline repository is an empty project in which you can start capturing details of your architecture. Download and explore the latest Sample Repository for an example of how to use Essential Open Source.
Β Troubleshooting
- On Windows 8 or Windows 10 platforms, if the installer fails to install the Essential Open Source plugins to the Protege install folder in Program Files, right-click on the installer program and use the 'run as administrator' facility.
- On newer Mac operating systems you may need to disable Gatekeeper for the install. See this article. Make sure you re-enable Gatekeeper after you have installed the software
- After installation, if Essential Viewer is not responding or the Report Service is not responding, check that the essential_viewer.war has been extracted and deployed to your web application server (e.g. Apache Tomcat) webapps folder. If the WAR file does not extract when you restart Apache Tomcat, you can deploy the WAR using the Tomcat Manager.
Running the Essential Open Source installer simplifies the installation process and helps to ensure that the Essential software components are installed correctly.
