Local MacOS X Machine Installation

Note that Appway 2022.2 has been renamed FNZ Studio 2022.2. In this article it is also referred to, generically, as Platform. Appway Studio (development environment) has been renamed FNZ Studio Composition.

Problem

I need to deploy the Platform on MacOS X using Apache Tomcat. What steps do I need to follow?

Solution

This article provides a step-by-step guide to deploying the Platform on a MacOS X machine using Apache Tomcat as Web Server and Servlet Container. This recipe complements the more general installation guidelines, and provides the specific parameterizations needed for installation on MacOS X.

IMPORTANT! In order to deploy the Platform, you need Java and the Apache Tomcat web server and Java Servlet container installed. Each version of Apache Tomcat supports just a given subset of Java versions.<br/> Check the technical requirements in our System Installation: Technical Requirements article for compatibility information for the Platform version you are installing.

This article is based on the example of a deployment of Appway 6.3.21 on MacOS X El Capitan using Tomcat 7 and Java 8 (Oracle JDK version 1.8.x). The guide can be adapted to all Platform versions, Java, and Apache Tomcat. Remember to pay attention to compatibility, especially considering that FNZ Studio 2022.2 runs only on Java 11.

Step 1: Setting Up Apache Tomcat 

In order to run the Platform on a local machine, you need to install and set up the Apache Tomcat web server and Java Servlet container: 

  1. Go to http://tomcat.apache.org and download the .zip package for the desired version of Apache Tomcat.
  2. Create your project directory (e.g: /Users/&lt;username&gt;/my-project, where &lt;username&gt; is your system username) and unzip the downloaded file into your project directory. Tomcat will be unzipped into directory /Users/&lt;username&gt;/my-project/apache-tomcat-8.x.xx.xx.
  3. For ease of use, shorten and rename this directory to /Users/&lt;username&gt;/my-project/tomcat. 
IMPORTANT! Do not use spaces or special characters (e.g. ü, ç) in the name of your project directory, as this may cause issues when starting the server or running the Platform.

Look at the installed Tomcat directory. It contains the following sub-directories: 

  • bin: Contains the startup script (startup.bat for Windows and startup.sh for Linux and MacOS X), shutdown script (shutdown.bat for Windows and shutdown.sh for Linux and MacOS X) binaries, as well as other binaries and scripts.
  • conf: Contains the system-wide configuration files, such as server.xml, web.xml, context.xml, and tomcat-users.xml.
  • lib: Contains the Tomcat system-wide JAR files, accessible by all web apps deployed on top of Tomcat. External JAR files (such as MySQL JDBC Driver) can be placed here manually.
  • logs: Contains Tomcat log files. You may need to check for error messages here.
  • webapps: Contains the web apps to be deployed. You can also place the WAR file for deployment here.
  • work: Tomcat's working directory used by JSP, for JSP-to-Servlet conversion.
  • temp: Contains temporary files.

Step 2: Setting up the Java JDK 

In order to have Tomcat running on your system, make sure that you have the correct Java version installed. Open the terminal and type java -version to check which version of Java you are running.

Figure 1 - Checking the version of Java

This screenshot shows an example of Java 8 installed on a user's machine.

If Java is not installed, or is not the correct version, go to the Oracle download area and download the latest version for your machine, and install it.

Step 3: Setting up and Starting the Apache Tomcat Server 

  1. Create the file setenv.sh using a text editor or download this sample. This file is used to configure the Apache Tomcat environment so that it can properly host the Platform. In the file, you need to specify your JAVA_HOME folder path and some parameters for the Java Virtual Machine, as depicted in Figure 1. You can retrieve the value for JAVA_HOME by running the following command in a Terminal window: /usr/libexec/java_homeFigure 2 - Setenv.sh

    Figure 1 — Setenv.sh

  2. Copy the setenv.sh file in the bin folder within the tomcat folder (/Users/&lt;username&gt;/my-project/tomcat/bin)

  3. Give execute permissions to all .sh files in the tomcat/bin folder.

    • Open a terminal
    • Navigate to the tomcat/bin folder [cd /Users/&lt;username&gt;/my-project/tomcat/bin]
    • Run this command: chmod +x *.sh (you may need sudo chmod +x *.sh)

  4. Run the command ./startup.sh in the tomcat/bin folder to start Apache Tomcat.

  5. (optional) You can tail the Apache Tomcat log using the command: tail -f  ../logs/catalina.out 

Open a browser window and navigate to http://localhost:8080. If Apache Tomcat was set up correctly, you should see something similar to the screen in Figure 2.

Figure 3 - Apache Tomcat start page

Figure 2 — Apache Tomcat start page

Step 4: Configuring One Node 

IMPORTANT! To complete setup, you require configuration files, license files, and key files. The configuration files are included here: GuideInstallAppwayonMacOSX (ZIP file). License and key files are not included, but existing customers may request these via their assigned CSM

  1. Create a new directory inside /Users/&lt;username&gt;/my-project/ with the name: cluster-storage. This folder is used to model the cluster-wide persistent store. All the nodes need to have access to the same folder: the persistent store.

  2. Next, create another folder inside /Users/&lt;username&gt;/my-project/ with the name: "node1". This folder is used to model a node.

  3. Move the Tomcat folder to node1.

  4. Create a folder in /Users/&lt;username&gt;/my-project/node1 with the name: data-home.

  5. Create two subfolders within this data-home folder: conf and extensions.  directory structure mac osx

  6. Copy the NmLoginServiceAdapter.jar file from the provided .zip file to this extensions folder. If you have other extensions to be deployed, copy the respective .jar files to the extensions folder. extensions mac osx

  7. Copy the conf.properties, content.properties, hazelcast.xml, and jaas.conf files to the conf folder.

  8. Copy the license file to …/data-home/conf/license.properties.  For a single-node test installation, use the license file which comes packaged in the WAR file. For all other cases, contact Support to request a license file.

  9. (optional) Open the conf.properties file with a Text Editor program and change the nodename and UID prefix:  uid prefix screenshot

IMPORTANT! The name of the cluster and the prefix must be unique! The prefix and nodename should be identical, except for capitalization.

  1. (optional) Edit the following line in the content.properties file to set a name for your instance:  nm.system.id = My Appway Instance

  2. Copy the WAR file (e.g nm-6.3.4.war) into the tomcat/webapps folder, rename it to ROOT.war, and remove the existing ROOT folder.

  3. Copy the NmJAASLoginModules.jar to tomcat/lib Define the nmdev realm in the file tomcat/conf/server.xml. Your server.xml file should look like this: server.xml screenshot

  4. Using the Terminal, navigate to your Tomcat bin folder: /Users/&lt;username&gt;/my-project/node1/node1/tomcat/bin and start up the server running the command :  ./startup.sh

  5. (optional) You can get the log of Tomcat by running the command: tail -f  ../logs/catalina.out 

Go back to your browser and navigate to localhost:8080. If everything is working correctly, you should see the following message: 

"It Works!" appears on the screen

Now go to the localhost:8080/admin page and you should see the login page of FNZ Studio Composition:

studio sign in page