Installation

This installation guide details the process for installing Essential Architecture Manager in the Stand Alone mode. Stand Alone Workstation / Notebook

Essential Architecture Manager is delivered in a single Java Archive (JAR) file containing all the software from the Essential Project and is for use on all computing platforms, Windows, Mac OS X, Linux, Unix. This installation guide takes you through the process of installing and configuring all the pre-requisite software, such as Protege and Apache Tomcat, and then installing the Essential Architecture Manager software.

A useful blog article is available which can help with the configuration of some of the software pre-requisites. You can read the article here
 

Components to install

The following components are required to install Essential Architecture Manager.
  • Protege. This is the core modelling tool platform for Essential AM. The "Full Protege" package is recommended.
  • Essential Widgets. A set of extension components from the Essential Project that are plugged into Protege. These include:
    • AutoTextWidget
    • ReportTabWidget (Essential Architecture Reporting tab)
  • Apache Tomcat or your favourite Java Web Application Server. The application server environment for running the Essential Viewer software.
  • Graphviz. This is used as a layout engine and is required to support the UML style views in Essential Viewer.
  • Essential Viewer
  • Essential Meta Model. The core meta model and base repository for Essential Architecture Manager.

1. Download

Essential Architecture Manager Installer JAR file downloadedHaving downloaded the essentialinstall.x.x.jar file from the Download section, please check that you have the software pre-requisites available.

2. Java Runtime Environment

Before starting the install of Essential Architecture Manager, confirm whether or not a JVM has been installed. From a command prompt, type:
java -version
The resulting message from Java should show a JVM version at or above version 1.5.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.

3. Install Protege

If you have not already installed Protege, install it by running the installation program.
 

3.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.5 or above) has already been installed, select that JVM.
    • Select either from the list show or find the version discovered in Step 3 using the "Choose Another" button. This may require investigation of the Java Control Panel in the Windows Control Panel. NOTE: You must select the specific java.exe file to use.
  • Select 'Next' until the installation completes.
 
 
 

3.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.5 or above) has already been installed (this will be the case on Mac OS X), select that JVM.
    • Select either from the list shown or find the version discovered in Step 3 using the "Choose Another" button.
  • NOTE: You must select the specific java.exe file to use.
  • Select 'Next' until the installation completes.

 

3.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.
This configuration is not required in Protege 3.3.1 and the preference is not available

4. 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.

Install Apache Tomcat by running apache-tomcat-N.x.x.x.exe, which will ask for the location of your preferred Java Virtual Machine (JVM).

Like Protege, Tomcat requires Java v1.5 or above. For simplicity, select the same JVM that was selected Essential Architecture Manager Installation Guide during the Protege installation. In this case when prompted by the Tomcat installer, select the path to the folder "jre".

5. Install Graphviz

6. Run Essential Architecture Manager Installer

Installer Welcome PanelHaving installed the pre-requisites, run the Essential Architecture Manager 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:

Double click on the Essential Install JAR File.

If, for some reason the installer is not recognised as an executable JAR file, use the following command at command prompt/terminal window:

java -jar essentialinstallxx.jar
(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.

7. Important Information and License Agreement

Essential Installer Information PanelThe Information Panel provides important information about the installation and pre-requisites. Please read these before proceeding to the license agreement.
Essential Installer License Panel

8. Select Essential Architecture Manager Packages to Install

Essential Installer Select Packages PanelThe Essential Architecture Manager 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.

9. Specify Protege and Tomcat Locations

Essential Installer Plugins PanelEssential Architecture Manager 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 <Tomcat Install>/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.
If you want to share your Essential Viewer with others in your organization, you can deploy the Essential Viewer to an instance of Tomcat that is running on a network server, if you can navigate to the Tomcat directory on the network server, do so from the 'Browse...' button for the Tomcat location field.

10. Install the Essential Repository

Essential Installer Repository PanelBoth the meta-model and the model for Essential Architecture Manager are contained in the repository which is controlled from a Protege project file, and has the file extension, .pprj
 
Next, specify to the target location of your empty Essential Architecture Manager Repository. The installer will create a directory to hold the meta-model and model configuration files in the folder that you specify. In stand-alone mode, we recommend using the file-based datastore for the repository. This directory will also contain the data files for the model and meta-model, e.g.
/EssentialAM/Repository

11. Essential Architecture Manager Server Configuration (Optional)

Essential Installer Server Configuration PanelEven 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 Architecture Manager 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.

12. Finished

Essential Installer Finished PanelThe installer will now install all the components of Essential Architecture Manager to the locations that you have specified in the above steps.
Essential Installer Done PanelWhen 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.
See the Automated Installer article for how to use this installation script.

Installation Complete

Your stand-alone installation of Essential Architecture Manager is now complete. Now go to the Getting Started Tutorials to find out more about capturing and analysing your architecture with Essential Architecture Manager.

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 Architecture Manager.

 
 

 Troubleshooting

  • On Windows Vista, Windows 7, Windows 8 or Windows 10 platforms, if the installer fails to install the Essential Architecture Manager plugins to the Protege install folder in Program Files, right-click on the installer program and use the 'run as administrator' facility.
  • 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 Architecture Manager installer simplifies the installation process and helps to ensure that the Essential software components are installed correctly. However, should you encounter any problems with the install the manual installation guide provides a useful starting point, as it contains extensive details and background into what the installer is doing.