Local Installation Guide

This guide walks you through installing Appian on a single machine with MySQL database for use in a local, non-production environment. While this guide uses the Windows operating system and MySQL database as examples, similar steps apply for Linux installations and other databases.

This guide does not cover the steps necessary to complete an enterprise installation. See the Windows Installation Guide or Linux Installation Guide for enterprise installation instructions.

Requirements

Download and install the following using the linked instructions:

Download the following before you begin your Appian installation:

Refer to the Prerequisites page and the System Requirements page for information on which version to download.

Install and setup MySQL workbench

1. Download MySQL (Windows x86, 64-bit MSI Installer). Download the Community version, not the Web Community version. The version number refers to the MySQL version, not the MySQL Workbench version.
2. Run the installer and continue until the Choosing A Setup Type page.
3. On the page Choosing A Setup Type, select Custom.
4. Click Next >.
5. Expand the folder of options and select MySQL Server and Connector/J.
6. Continue through with default settings and complete installation.
7. Download MySQL WorkBench (Windows x86, 64-bit MSI Installer). The version number refers to the MySQL Workbench version, not the MySQL version.
8. Run the installer and complete installation.
9. To set up MySQL Workbench for Appian:
   • Open MySQL Workbench, create a new connection with any name, setting hostname: localhost and port: 3306.
   • Set a username of root and password of password. Any values can be used, and they do not need to be unique to the local installation.
   • Right-click the newly created connection and select Open Connection to open the connection.

   • Create a database schema by clicking the cylindrical schema symbol on the top left of the MySQL Workbench window as shown in the screenshot below.

     

   • Name this schema which will serve as the primary datasource based on the version. This will be referred to as APPIAN_SCHEMA.
   • Apply the database schema and click Finish.
   • Repeat the previous three steps to create another database schema to serve as the business datasource. This will be referred to as BUSINESS_SCHEMA.
     • Note: The two schemas need to be unique to this Appian installation since each serves as datasources for the installation.

Refer to the System Requirements page for more information.

Installation

During the installation and configuration process, you will install Appian and then use the configuration script to configure it.

The following placeholders are used throughout this document to keep the installation directories easy to read. Replace XXX in the example location with the version number, such as 161 or 171 for Appian 16.1 and 17.1 respectively.

Part One: run the Appian installer

Appian is installed using a graphical installer. The installer automatically installs Appian in C:\appian unless you specify another directory. Do not install Appian in a directory where another version of Appian is already installed. Do not use the following characters in the name of your installation directory: & ^ = ( ) <space>

To install Appian:

1. Temporarily disable any antivirus software or search indexing utilities running on the server.
2. Run the installer.
   • Tip: If you are using Windows 7, right-click the installer and select Run as administrator.
3. Click Next in the window and again on the following window to proceed to the window which allows the user to set the Destination Folder.
4. Under the section Destination Folder, click Browse, and then specify the desired location for the APPIAN_HOME directory. To create this target directory:
   • click Make New Folder.
   • Place the folder in C:\ and name the folder appianXXX, where XXX is the current version number of Appian to install. If you are installing a second instance of Appian, name it appianXXX_2. These directories allow you to have multiple local installations of Appian.
   • Create another folder named appian and place it within C:\appianXXX. This would result in a final target directory such as C:\appianXXX\appian\.
5. Click OK to select the folder C:\appianXXX\appian\.
6. Click Next on the window and again on the following window to proceed with the installation.
7. Wait for the installation to complete. This may take several minutes.
8. Click Finish to close the installer.
9. Set JAVA_HOME and PATH Environment Variables

A Program Compatibility Assistant dialog may appear after the installer closes. This issue does not affect the Appian installation. If this happens, click This program installed correctly to dismiss the warning.

Part two: Run the configure script

The configure script, configure.bat, is a command line utility that provides a menu-driven interface for executing configuration and deployment tasks. You will use the first three menu options during this part. Later, you will return to the configure script to complete the configuration and deployment.

To create a local configuration repository (REPO_HOME)

1. Open the command prompt, and then run the following command:

   1
   <APPIAN_HOME>\_admin\_scripts\configure\configure.bat
   

2. Choose 1 - Create or select repository.
   • Tip: You just need to type the number and press Enter to specify which menu option you wish to run.
3. Specify the path for the configuration repository.
   • Tip: You do not need to create the directory prior to entering it in the configure script. This also applies for the initial backup below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
======================================================================
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
> 1


Enter path of repository directory
B - Back
Q - Quit
> C:\appianXXX\repo\appian

When you have finished, you will see something similar to the screenshot below (notice that more menu options are now available). The example in the screenshots uses C:\appianXXX\repo\appian as the path.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
======================================================================
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
> 1


Enter path of repository directory
B - Back
Q - Quit
> C:\appianXXX\repo\appian
Repository updated to C:\appianXXX\repo\appian

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

This script assists with configuring Appian on various environments.
======================================================================

Repository location: C:\appianXXX\repo\appian


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
>

To create the initial backup

1. With the command prompt still open, run 2 - Create initial backup of Appian installation.
2. Specify the path for the local backup (for example C:\appianXXX\backup\appian.)

To register an environment

1. With the command prompt still open, run 3 - Register an environment.
2. Specify a name for the environment (for example, you may choose to use dev if you are creating a development environment). Leave the configure script command window open.

You will need to use the name of the registered environment when configuring MySQL in the next part. The environment is referred using the placeholder ENVIRONMENT throughout the remainder of this guide.

Part three: Configure the Appian properties and MySQL files

Custom properties

Make the following changes to the custom.properties.<ENVIRONMENT> file:

1. Go to <REPO_HOME>\conf.
2. Open custom.properties.<ENVIRONMENT> in a text editor.
   • Tip: If your custom.properties file does not have the .<ENVIRONMENT> extension, it may be due to your computer’s known extensions setting.

3. Set conf.suite.SCHEME to http by removing the letter s at the end and uncommenting the line by deleting the # sign:

   1
   #conf.suite.SCHEME=https
   

   which should now appear as

   1
   conf.suite.SCHEME=http
   

   • This configuration bypasses the need for a certificate to be installed. It is only supported for local installations and is not supported for production environments or any environment that is accessible over the internet. For production or internet-accessible installations, you must use https instead of http. For more information on configuring a web server to run over https, see Creating a Certificate.

4. Uncomment the following line, replacing <YOUR_VALUE> with your machine's fully qualified domain name (FQDN), which uses the pattern myhost.domain.com:

   1
   #conf.suite.SERVER_AND_PORT=<YOUR_VALUE>:8080
   

   which should now appear as:

   1
   conf.suite.SERVER_AND_PORT=<YOUR_VALUE>:8080
   

   • Tip: You can find your computer's FQDN by clicking Start, right-clicking Computer, and then clicking Properties. The FQDN is listed in the Computer name, domain, and workgroup Settings section. Include any suffix such as .company.com tag, and do not include the angle brackets <> around YOUR_VALUE. A hypothetical FQDN is MY355COMP86NAME.acme.com.

5. Uncomment the following lines, and set the values equal to the JNDI name, jdbc/AppianDS, used in <REPO_HOME>\conf\tomcatResources.xml.<ENVIRONMENT> (do not use quotes around the JNDI names in this file):

   1
   #conf.data.APPIAN_DATA_SOURCE=
   

   which should now appear as

   1
   conf.data.APPIAN_DATA_SOURCE=jdbc/AppianDS
   

   • Note: JNDI names do not have to be unique across Appian local installations.
6. Save the file.

Service manager password

1. Go to <APPIAN_HOME>\services\bin\.
2. Run password script (password.bat), using the -p option to specify a password.
3. Copy the resulting file from <APPIAN_HOME>\services\conf\service_manager.conf to <REPO_HOME>\services\conf\service_manager.conf.<ENVIRONMENT>. You will need to create the <REPO_HOME>\services\conf\ directory if you have not previously completed this step.

MySQL files

Next, you will need to change the data source for your MySQL files from the default data source of MariaDB to a MySQL database.

To do this:

1. Open <REPO_HOME>\conf\tomcatResources.xml.<ENVIRONMENT>.

2. In the line below, replace the JDBC URL subprotocol mariadb with mysql and appian_primary with your primary data source name, such as appianXXX_primary:

   1
   url="jdbc:mariadb://localhost:3306/appian_primary?useOldAliasMetadataBehavior=true&useUnicode=true&characterEncoding=utf8"
   

   If your datasource name is appianXXX_primary, this line should now appear as:

   1
   url="jdbc:mysql://localhost:3306/appianXXX_primary?useOldAliasMetadataBehavior=true&useUnicode=true&characterEncoding=utf8"
   

3. Update the driverClassName configuration value to com.mysql.jdbc.Driver.
4. Save the file.

The final configuration should look something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 <Resource name="jdbc/AppianDS"
    factory="com.appiancorp.tomcat.datasource.EncodedPasswordDataSourceFactory"
    type="javax.sql.DataSource"
    driverClassName="com.mysql.jdbc.Driver"
    url="jdbc:mysql://localhost:3306/appianXXX_primary?useOldAliasMetadataBehavior=true&amp;useUnicode=true&amp;characterEncoding=utf8"
    username=""
    password=""
    initialSize="5"
    maxActive="100"
    defaultTransactionIsolation="READ_COMMITTED"
    maxWait="30000"
    minIdle="5"
    minEvictableIdleTimeMillis="90000"
    timeBetweenEvictionRunsMillis="450000"
    validationQuery="SELECT 1"
    testOnBorrow="true"
  />

Part four: MySQL data source password setup

We are now ready to return to the configure script to encode the MySQL data source password for use by Appian. This capability is available from the 6 - Tools menu option.

1. If you have closed out of the configure script, use the following command to reopen it:

   1
   <APPIAN_HOME>\_admin\_scripts\configure\configure.bat
   

2. Type 6, and then press Enter.
3. Type 1, and then press Enter.
4. Provide the password, MYSQL_PASSWORD, for the user that will connect to the MySQL database.
5. Copy the encoded password hash, referenced as MYSQL_PW_HASH, for use in the next procedure.
6. Type Q to quit.
7. Open <REPO_HOME>\conf\tomcatResources.xml.<ENVIRONMENT>.
8. Locate the <Resource> tag with a name of jdbc/AppianDS
9. Update the username="" line to include the username you previously configured for MySQL above, root
10. Update the password="" line to include MYSQL_PW_HASH that you generated above

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
======================================================================
Configure Appian

This script assists with configuring Appian on various environments.
======================================================================

Repository location: C:\appianXXX\repo\appian


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
> 6

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

This script assists with configuring Appian on various environments.
======================================================================

Repository location: C:\appianXXX\repo\appian


Select a tool to execute
1 - Encode passwords for use in data source configuration
2 - Configure Tomcat clustering by specifying a node name
B - Back
Q - Quit
> 1


Enter the password to encode for use in datasource configuration
B - Back
Q - Quit
> mypassword
Encoded password: p5Ccm85AkVo1JGo3PBU7eg==

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

This script assists with configuring Appian on various environments.
======================================================================

Repository location: C:\appianXXX\repo\appian


Select a tool to execute
1 - Encode passwords for use in data source configuration
2 - Configure Tomcat clustering by specifying a node name
B - Back
Q - Quit
>

Part five: Adding the MySQL driver

Appian requires the MySQL Connector/J driver, downloaded in the Requirements section.

1. In folder: <REPO_HOME>\, create directory \tomcat\apache-tomcat\lib\.
2. Add the MySQL Connector/J driver, mysql-connector-java-X.X.XX-bin.jar, contained in the downloaded file mysql-connector-java.X.X.XX.zip to the lib\ folder.

Part six: Install the temporary product license

Copy the temporary license files from the Requirements section.

1. Place k3.lic inside the <REPO_HOME>\server\_bin\k\win64 directory.
2. Place k4.lic inside the <REPO_HOME>\data-server\engine\bin\q\w64 directory.

Part seven: Deploy the configurations

Use the configure script to validate your environment's configuration and deploy Appian.

1. Open the command prompt, and then run the following command:

   1
   <APPIAN_HOME>\_admin\_scripts\configure\configure.bat
   

2. Choose 4 - Validate configurations.
3. Choose 5 - Deploy configurations, select 1 - <ENVIRONMENT>, and then select 1 - Deploy configurations to Appian.
4. Type Q to quit.

Part eight: Start Appian and log In

After you have completed the process above, you are ready to start Appian for the first time. Starting and stopping the system properly is very important for maintaining the highest levels of system availability. Improper shutdowns can cause system issues.

For your convenience, the instructions to start Appian are included below. See Starting and Stopping Appian for more information about stopping the system correctly.

Open the command prompt, and then run the following commands (wait for each to finish before starting the next):

• <APPIAN_HOME>\services\bin\start.bat -p <password> -s all
• <APPIAN_HOME>\data-server\bin\start.bat
• <APPIAN_HOME>\search-server\bin\start.bat
• <APPIAN_HOME>\tomcat\apache-tomcat\bin\start-appserver.bat

Appian has started successfully when the command line displays a message similar to:

1
INFO [main] org.apache.catalina.startup.Catalina.start Server startup in 377928 ms

If any configurations are changed while troubleshooting, rerun Part Seven: Deploy the Configurations before starting Appian again.

Once started, you will be able to

1. In a browser, navigate to http://<FQDN>:8080/suite/design/users.
   • Tip: Include any suffix such as .company.com tag in the FQDN name.
2. Log in with the username Administrator and temporary password admin.
3. Change the system administrator's password when prompted.
4. Click on the Create User button and create a new user of type System Administrator.

The default Administrator account cannot access the Admin Console, so a separate account is required to complete the following steps.

Part nine: Configure the business data source

The first thing that you should do after logging into Appian for the first time is configure it to connect to a business data source.

To set up the Business Data Source:

1. Log in as the newly created user.
2. Navigate to http://<FQDN>:8080/suite/admin.
3. Using the left side options, Go to the Data Sources page of the Admin Console.
4. click on the New Data Source link.
5. In the Name field, enter any name for the business data source JNDI name, starting with "jdbc/".
   
   • Note: the JNDI name does not need to be unique across Appian local installations.
6. In the field Type, select MySQL.
7. Enter in the MySQL Workbench username root and the password password (not the hash).

8. Enter the following connection string:

   1
   jdbc:mysql://localhost:3306/<BUSINESS_SCHEMA>?useOldAliasMetadataBehavior=true
   

   where BUSINESS_SCHEMA is the one noted in the Requirements section, such appianXXX_business where XXX is the Appian version number. Do not include quotations around the connection string and do not include the angle brackets <> around BUSINESS_SCHEMA.

9. Click Test Connection. If the connection fails, verify the settings above and whether they match the information entered in the Requirements section.
10. Click Save.

Feedback