Installing Appian 17.2 on Centos 7

As part of a recent project, I was provided the opportunity to evaluate Appian (a Business Process Management Suite) and how it can fit the requirements. As part of the exploratory phase, I had to understand Appian’s architecture and install an evaluation instance.

This post will describe the installation steps I took to get Appian 17.2 running on a clean installation of CentOS 7.

Note: This post serves as a future reference, and is not an endorsement of the product/technologies listed. Do refer to the official documentation for updated/additional details. Please contact Appian directly if you do not have any of the Appian related items, such as the installation file and/or license.

Architecture

  • Hardware
    • Operating System: CentOS 7 (Base Environment: Minimal Install, 64 bit)
    • RAM: 4 Gibibytes
    • HDD: 100 Gigabytes
    • CPU: 2 cores
  • Software (Versions are included for completeness)
    • Oracle Java SE Development Kit (JDK) 8u131
    • Red Hat JBoss Enterprise Application Platform (version 6.4.0)
    • MySQL Community Server 5.7.18
    • MySQL Connector/J 5.1.42
    • Appian 17.2 Installation Binary

Pre-Requisites

  • Follow the official Appian documentation, under “Installation Guide > Prerequisites” to:
    • Obtain a valid Appian license with file name “k3.lic” + perform necessary configuration on the OS,
    • Install Oracle JDK 8 + set Java bin to PATH environment (as root user),
    • Create a non-root Appian Application User Account,
    • Increase the maximum open file limit for the non-root Appian Application User Account, and
    • Verify the Server System Locale Setting

Installation Steps

Step 0: Set CLI path to home directory

$ cd ~

In this write up, I performed all installations within the home directory of the non-root Appian Application User Account. There was no observed impact on Appian’s key functionalities.

If you choose to use a different directory in your setup procedure, do ensure that the Appian Application User Account has the necessary permissions to read and/or write to the path(s).

Step 1: Installing Red Hat JBoss Enterprise Application Platform 6.4.0

Run the JBoss installation file, and you will encounter the following steps in order:

  • Select language
  • Accept EULA
  • Select the installation path
  • Select the packs you want to install
  • Create an administrative user
  • Configure runtime environment
  • Generate an automatic installation script and properties file

I accepted the defaults for all, except the installation path: I chose to install within the home directory of the non-root Appian Application User Account.

$ java -jar /(path_to_file)/jboss-eap-6.4.0-installer.jar
...
Select the installation path:
/home/(non-root_appian_user)/EAP-6.4.0

Step 2: Install MySql Database

I followed this excellent tutorial from DigitalOcean (https://www.digitalocean.com/community/tutorials/how-to-install-mysql-on-centos-7).

In a nutshell, the commands I executed as root user were:

  • Install RPM file to update the repository
    # rpm -ivh (mysql_community_repo)
  • Locate and Install MySql Community Server (64 bit)
    # yum search mysql
    # yum install mysql-community-server.x86_64
  • Start MySql Process
    # systemctl start mysqld
  • Change root password and configure for secure installation
    # grep 'temporary password' /var/log/mysqld.log
    # mysql_secure_installation
  • Test new MySql root password as non-root Appian Application User
    $ mysql -u root -p

Step 3: Installing Appian

As non-root Appian Application User, create the Appian application folder. In the code below, my Appian application folder is called “appian_home”, within the user’s home directory.

Next, run the installation binary and provide the installation path to the newly created Appian folder when prompted.

$ mkdir ~/appian_home
$ ./(appian_installation_binary)
This will install Appian on your computer.  Continue? [n/Y] y
...
Where do you want to install Appian? /home/(non-root_appian_user)/appian_home

Installing Appian in /home/(non-root_appian_user)/appian_home
...
Installation complete.   

Step 4: Run Appian Configuration Script

Appian comes with a really nifty Configuration Script that makes configuration and deployment a breeze. For this convenience, I chose this method to complete the installation.

To get started, execute the Appian Configuration Script:

$ ~/appian_home/_admin/_scripts/configure/configure.sh
===================================================================
Configure Appian

This script assists with configuring Appian on various Environments 
===================================================================

1 - Create or select repository 
2 - Create initial backup of Appian installation 
B - Back 
Q - Quit  
>

There will be a list of options provided, and a short description of each option is as follows:

[1] – Create a repository, or select an existing one, to store the various environment settings (allows you to manage multiple configurations for various environments. E.g. development connects to local MySql, but production connects to a cloud instance)

[2] – Creates a backup of the current Appian configuration (useful to do a backup before making changes)

Step 5: Create a Configuration Repository

Select [1] from the Configuration Script options, and it will prompt you to provide the path to the Configuration Repository directory.

The configuration script will then create the folder if it does not exist. Do note that the relevant permissions must be set.

In the commands below, I named mine as ‘appian_repository’ and saved it within the non-root Appian Application User’s home directory.

> 1 (Selected option from Configuration Script)

Enter path of repository directory 
B - Back
Q - Quit 
> /home/(non-root_appian_user)/appian_repository
...
Repository updated to /home/(non-root_appian_user)/appian_repository

Step 5a: Understanding the Configuration Repository Structure

You’ve just created the repository folder, now its time to understand it. Navigate to the Configuration Repository directory and you will see the following folders:

bin – JBoss Application Server configuration files (Currently, Configuration Script only supports JBoss)

ear – Appian environment configuration files. “ear” stands for “Enterprise Application aRchive”.

environments.properties – contains key-value property pairs about the various environment

search-server – The Elasticsearch server that provides search and data retrieval capabilities for Appian

server – To contain the Appian License Key(s) for the respective environment(s)

Step 5b: New Options Available in the Configuration Script

After creating the configuration repository, more options open up in the Configuration Script:

===================================================================
Configure Appian

This script assists with configuring Appian on various Environments 
===================================================================

Repository location: /home/(non-root_appian_user)/appian_repository
1 - Change repository
2 - Create initial backup of Appian installation
3 - Register an environment 
4 - Validate configurations 
5 - Deploy configurations 
6 - Tools 
B - Back
Q - Quit
>

A brief description of the new options available:

[3] – Create a new environment to be stored within the repository folder. Configuration files suffixed with the environment name will be created from the template

[4] – Checks if your configuration has the necessary items (i.e. is valid. does not check for correctness of values)

[5] – Copies/Deploys the environment configuration files to the application server and Appian

[6] – Utilities for helping with the configuration process

Step 6: Backup the Default Appian Configurations

Though optional, it will be good to backup the default Appian configurations before deploying new ones.

> 2 (Selected option from Configuration Script)

Enter path to directory for back up Appian
B - Back
Q - Quit
> /home/(non-root_appian_user)/appian_backup
Backup successful in directory /home/(non-root_appian_user)/appian_backup

Step 7: Create a New Appian Environment Configuration

Appian Configuration Script calls this as “registering” a new environment. Doing so will create new instances of the configuration templates, suffixed with the environment name.

Subsequently, all edits to the various environments will be done to the files with the corresponding environment name suffix.

> 3 (Selected option from Configuration Script)

Existing environments: None
Add a new environment
B - Back
Q - Quit 
> (environment_name)
The environment (environment_name) was registered successfully.

After creating your new environment, type “Q” to exit the Configuration Script.

Step 8: Add MySql JDBC Driver to JBoss Configuration Sub-folder

Save the MySql JDBC driver in the following path: ~/appian_repository/bin/jboss/jboss-eap-6.4/modules/com/mysql/jdbc/main/

$ mkdir -p ~/appian_repository/bin/jboss/jboss-eap-6.4/modules/com/mysql/jdbc/main/
$ (copy the JDBC driver to the above path, e.g. scp or wget)

Create and edit “module.xml” to reference the driver:

$ vi ~/appian_repository/bin/jboss/jboss-eap-6.4/modules/com/mysql/jdbc/main/module.xml

And paste the following text inside:

Note:

  • Due to html tag parsing by wordpress engine, please replace all ( to < before saving to module.xml
  • Please change the path value to be the same file name of your MySql JDBC driver
(module xmlns="urn:jboss:module:1.0" name="com.mysql.jdbc">
  (resources>
    (resource-root path="mysql-connector-java-5.1.42-bin.jar"/>
  (/resources>
  (dependencies>
    (module name="javax.api"/>
    (module name="javax.transaction.api"/>
  (/dependencies>
(/module>

Step 9: Configure JBoss to use JDBC Driver when Creating a Data Source Connection in Standalone Mode

The nifty Configuration Script has already created a template for us. However, minor edits are required.

Edit the standalone.xml.(environment_name):

$ vi ~/appian_repository/bin/jboss/jboss-eap-6.4/standalone/configuration/standalone.xml.(environment_name)

Locate the tag with xmlns=”urn:jboss:domain:datasources:1.2″, and modify it to the following:

Note:

  • Due to html tag parsing by wordpress engine, please replace all ( to <
(subsystem xmlns="urn:jboss:domain:datasources:1.2">
    (datasources>
        (drivers>
            (driver name="com.mysql.jdbc" module="com.mysql.jdbc">
                (driver-class>com.mysql.jdbc.Driver(/driver-class>
                (xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource(/xa-datasource-class>
            (/driver>
        (/drivers>
    (/datasources>
(/subsystem>

Save the changes and exit the text editor.

Step 10: Save Database User Credentials in JBoss

It is dangerous to store the database user’s password in plain text – thankfully the Appian configuration script comes with a simple encoder. Use it to encode the database user password – it can be found under option [6].

$ ~/appian_home/_admin/_scripts/configure/configure.sh
...
> 6 (Selected option from Configuration Script)

Select a tool to execute
1 - Encode passwords for use in JBoss data source configuration
B - Back
Q - Quit
> 1 

Enter path for JBoss directory
B - Back
Q - Quit 
> /home/(non-root_appian_user)/EAP-6.4.0
Enter the password to encode for use in JBoss data source configuration
B - Back 
Q - Quit
> (enter database login password here)
Encoded password: (encoded password displayed here)

Exit the Configuration Script and re-open the JBoss standalone mode configuration file:

$ vi ~/appian_repository/bin/jboss/jboss-eap-6.4/standalone/configuration/standalone.xml.(environment_name)

Locate the security-domain tag with the name=”ds-name-security-primary”, and enter the username and encoded password into the respective sub-tags.

Note:

  • Due to html tag parsing by wordpress engine, please replace all ( to <
(security-domain name="ds-name-security-primary" cache-type="default">
    (authentication>
        (login-module code="org.picketbox.datasource.security.SecureIdentityLoginModule" flag="required">
            (module-option name="username" value="(database username)" />
            (module-option name="password" value="(encoded password)" />
        (/login-module>
    (/authentication>
(/security-domain>

Step 11: Configure Database Connection Properties

Now that JBoss has been configured to use the JDBC driver to connect to the database using a valid login username and password, lets configure the connection properties.

The Configuration Script has created a default one for us, so let’s edit it to save time.

Edit the Appian MySql Datasource file:

$ vi ~/appian_repository/bin/jboss/jboss-eap-6.4/standalone/deployments/appian-mysql-ds.xml.(environment_name)

Things to do: 1) Take note of the JNDI name, 2) Take note or change the database name if desired, and 3) Change “use-java-context” to be true

You should now have something similar to the following:
Note:

  • Due to html tag parsing by wordpress engine, please replace all ( to <
(?xml version="1.0" encoding="UTF-8"?>
(datasources xmlns="http://www.jboss.org/ironjacamar/schema">
  (!-- System Datasource -->
  (xa-datasource
      jndi-name="jdbc/AppianDS"
      pool-name="MySqlDS"
      enabled="true"
      use-java-context="true">
    (xa-datasource-property name="URL">jdbc:mysql://localhost:3306/appian_primary?useOldAliasMetadataBehavior=true(/xa-datasource-property>
    (xa-datasource-property name="useUnicode">true(/xa-datasource-property>
    (xa-datasource-property name="characterEncoding">UTF-8(/xa-datasource-property>
    (xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource(/xa-datasource-class>
    (driver>com.mysql.jdbc(/driver>
    (security>
      (security-domain>ds-name-security-primary(/security-domain>
    (/security>
    (transaction-isolation>TRANSACTION_READ_COMMITTED(/transaction-isolation>
    (xa-pool>
      (min-pool-size>5(/min-pool-size>
      (max-pool-size>100(/max-pool-size>
    (/xa-pool>
    (timeout>
      (blocking-timeout-millis>5000(/blocking-timeout-millis>
      (idle-timeout-minutes>5(/idle-timeout-minutes>
    (/timeout>
  (/xa-datasource>
(/datasources>

Step 12: Create the Appian Database in MySql

Connect to MySql to create the database, and grant the necessary privileges to the user account.

In my example, I use the MySql root user – while its not the most secure setting, it fits my needs.

$ mysql -u root -p
mysql> create database appian_primary; 
Query OK, 1 row affected (0.00 sec)
mysql> (todo: grant access to non-root user that will be used by Appian in production mode)
mysql> exit
Bye
(change "appian_primary" database name if you changed the default value in step 11)

Step 13: Configure Appian Properties

Open the Appian Configuration File

$ vi ~/appian_repository/ear/suite.ear/conf/custom.properties.(environment_name)

Step 13a: Set the Connection Protocol

Under the General section:

conf.suite.SCHEME=http

Step 13b: Set the Appian Server URL and Port

Under the General section:

conf.suite.SERVER_AND_PORT=(URL/IP):(PORT)

For JBoss, the port should be set to 8080

Step 13c: Increase the number of concurrent running processes for 64-bit OS

Under Process Execution section:

server.conf.processcommon.MAX_EXEC_ENGINE_LOAD_METRIC=120

Step 13d: Connect to MySql Database Through JBoss’ Database Connection

Under Data Sources section, add the following line:

conf.data.APPIAN_DATA_SOURCE=java:/jdbc/AppianDS

Save and close the Appian Configuration File

Step 13e: Disable Cookie Config

Because we changed the connection protocol (i.e. the scheme) to HTTP, we need to tell Appian not to use cookies.

$ vi ~/appian_home/ear/suite.ear/web.war/WEB-INF/web.xml

Delete the following lines:
Note:

  • Due to html tag parsing by wordpress engine, please replace all ( to <
 (cookie-config>
    (http-only>true(/http-only>
    (secure>true(/secure>
(/cookie-config>
(tracking-mode>COOKIE(/tracking-mode>

Save and close the file after editing.

Step 14: Create Default System Administrator

Create the System Administrator login credentials to be used at the start:

$ vi ~/appian_repository/ear/suite.ear/conf/passwords.properties.(environment_name)

Uncomment and edit the following self-explanatory fields:

conf.password.ADMIN_USERNAME
conf.password.ADMIN_FIRST_NAME
conf.password.ADMIN_LAST_NAME
conf.password.ADMIN_EMAIL
conf.password.ADMIN_TEMPORARY_PASSWORD

Save and close the file after editing.

Step 15: Copy Appian License

Copy and rename the Appian License file to the following directory:

$ cp /(path_to_file)/k3.lic ~/appian_repository/server/_bin/k/linux64/k3.lic.(environment_name)

Step 16: Deploy Configuration to JBoss and Appian

Deploy the JBoss and Appian configurations using the Configuration Script:

$ ~/appian_home/_admin/_scripts/configure/configure.sh
...
> 5 

Select an environment to deploy the configuration files 
1 - (environment_name)
> 1

Select the type of deployment to perform on the environment (environment_name)
1 - Deploy configurations to Appian
2 - Deploy configurations to JBoss
3 - Deploy configurations to both 
B - Back
Q - Quit 
> 3
JBoss configurations successfully deployed for environment (environment_name)
Appian configurations successfully deployed for environment (environment_name)

Step 17: Start Appian

Follow the official documentation (https://docs.appian.com/suite/help/17.2/Starting_and_Stopping_Appian.html) to start Appian and its necessary services.

Commands are:

Test to see if any running instance 
$ ps -ef | grep /k
$ ps -ef | grep /java

Start Appian
$ ~/appian_home/server/_scripts/start-suite.sh

Check Appian Startup Progress (Ensure all display "okay" status)
$ ~/appian_home/server/_scripts/diagnostic/checkengine.sh

Start Elasticsearch Server
$ ~/appian_home/search-server/bin/start.sh

Start JBoss Application Server (the first time takes longer, ~ 10 mins)
$ ~/EAP-6.4.0/bin/standalone.sh
...
JBoss EAP 6.4.0.GA (AS 7.5.0.Final-redhat-21) started in 84480ms

Step 18: Open Firewall Ports

As root user, use firewall-cmd to open the necessary ports for remote access.

# firewall-cmd --permanent --add-port=8080/tcp

Step 19: Login to Appian

Open a supported web browser and navigate to SERVER_URL/IP:PORT/suite/design

Login with the default “Administrator/admin” account, or the earlier defined administrator credentials in the passwords.properties.(environment_name) file.

And you’re done – phew!

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s