Configure Script

The configure script allows you to manage and deploy custom configurations to Appian installations in a repeatable manner. It also aids with the initial setup of the configurations required for running Appian.

Results of the script are logged to configure.log in the same directory in which the script resides.

Use of a version control system in conjunction with the script is highly recommended. The script creates a repository directory in which all configuration files are stored before being deployed. This directory should be version controlled using your preferred version control mechanism, such as Git.

Life Cycle

The typical life cycle of using the configure script to aid configuration management with Appian is as follows:

  1. Install Appian and the prerequisites software.
  2. Create a repository for configurations using the configure script.
  3. Back up the new Appian installation before applying any configurations.
  4. Register an environment with the configure script.
  5. Edit the configuration files in the repository to set the relevant properties for the given environment.
  6. Validate the configurations using the configure script.
  7. Use the configure script to deploy the configurations to Appian.

Note: The configure script does not change configurations. It deploys the configurations that are stored in its repository. You must change configuration files like custom.properties, password.properties, and appian-topology.xml. Change these files in the configure script repository, version control the changes, and then use the configure script to deploy the changes.

Running the Script

To run the script

  1. Navigate to <APPIAN_HOME>/_admin/_scripts/configure
  2. Run configure.sh (or configure.bat on Windows)

The script provides a menu driven interface for executing the various configuration and deployment tasks. The script can also be run in a non-interactive manner by passing parameters on the command line when executing the script—see the Silent Mode section for details.

Creating the Configuration Repository

The first step when running the configure script on a new machine is creating a repository. The configuration repository is where your custom configurations will be stored.

  1. Run configure.sh (or configure.bat on Windows)
  2. From the main menu, select 1 - Create or select a repository
  3. Provide the path to a directory in which the repository will be created
  4. Once you have created the repository, use your preferred version control system to version control the repository directory

After you create a repository, the repository location is displayed in the menu's banner and additional menu options become available. Also, the menu option to create a repository becomes an option to change the repository location, which creates a new repository at the given new location.

Backing up Appian

Backing up the Appian directories is recommended before deploying any custom configurations.

Run this script option after installing Appian but before deploying any custom configurations in order to create a backup copy which can be restored. To undo all custom configurations, restore from this backup by deleting the directories from Appian and copying these backup directories to the <APPIAN_HOME> directory.

  1. Run configure.sh (or configure.bat on Windows)
  2. From the main menu, select 2 - Create initial backup of Appian installation
  3. Provide a directory to which the files will be copied

The configure script does not back up Appian data. Use the scripts described in the Data Maintenance page to manage data backups.

See also: Data Maintenance

Registering an Environment

This option is only available once you have created a repository.

An environment is an Appian instance that has different configurations than other instances. For instance, you may have one set of configurations for your development environment and a different set of configurations for your production environment.

Creating a new environment creates an initial copy of configuration files from templates that are specific to that environment. When deploying configurations, the environments you create will be available as selectable options and the corresponding files will be copied to the target instance of Appian.

  1. Run configure.sh (or configure.bat on Windows)
  2. From the main menu, select 3 - Register an environment
  3. At the next prompt, give the environment a name (for example, prod, staging, or dev)

The following names are reserved and cannot be used as an environment name:

  • log
  • template
  • example
  • properties
  • txt
  • xml
  • bat
  • sh
  • jar
  • sec
  • jpg
  • gif
  • png
  • ear
  • war
  • dodeploy

Editing Configurations

The configure script does not modify values in the configuration files in the repository.

After registering an environment, set the desired configuration values for that environment by editing the configuration files suffixed with the environment name. Additionally, you can provide new files in the configuration repository that will be copied to the target when deploying. For instance,

  • A k3.lic.env file placed in <REPO>/server/_bin/k/linux64/ and a k4.lic.env file placed in <REPO>/data-server/engine/bin/q/l64/ will be copied to the corresponding directories in <APPIAN_HOME> when the env environment is deployed.

For more details on setting configuration values see:

Validating Configurations

This option is only available once you have created a repository.

The configure script can conduct a minimal review of the configuration files to verify that custom.properties is present and that the essential properties are defined there.

  1. Run configure.sh (or configure.bat on Windows)
  2. From the main menu, select 4 - Validate configurations
  3. The validation will inspect all registered environments and either report success or any validation errors back to the console

Validation of a specific environment is also performed automatically when you deploy configurations for the selected environment.

Deploying Configurations

This option is only available once you have registered an environment.

The configuration script deploys configurations by copying the configuration files from the repository directory to the target Appian directory.

Before executing this option you must edit the appropriate configuration files for the environment that you wish to deploy.

  1. Run configure.sh (or configure.bat on Windows)
  2. From the main menu, select 5 - Deploy configurations
  3. Select the environment for which configurations should be deployed
  4. Select to deploy configurations to Appian
  5. The configuration files will be deployed to the selected targets

If you have not run a backup before deploying configurations, the script will prompt you to run an optional backup before deploying configurations.

Tools

The tools menu contains utilities to aid in the configuration and deployment of Appian.

Encoding passwords for use in data source configurations

  1. Run configure.sh (or configure.bat on Windows)
  2. From the main menu, select 6 - Tools
  3. Select 1 - Encode passwords for use in data source configuration
  4. Provide a password to be encoded (the password will not be stored)
  5. The encoded password will be returned. Use this password in datasource configuration files.

Configure Tomcat clustering by specifying a node name

  1. Run configure.sh (or configure.bat on Windows)
  2. From the main menu, select 6 - Tools
  3. Select 2 - Configure Tomcat clustering by specifying a node name
  4. Provide the worker node name from your web server configuration that corresponds to this server.

Silent Mode

The above activities are available as command line options allowing you to build scripts that bypass the menu-driven interactive interface. The silent mode is accessed by passing -silent as a parameter to the script. The task name for the desired activity must be passed as task=value, plus any parameters necessary for that task. Additional parameters and their corresponding values are passed in the parameter=value format. For example, to run the deployAppianConfigurations task:

1
configure.sh -silent task=deployAppianConfigurations environmentName=dev
Activity Task Name Parameters Prerequisites
Create Repository createRepository
  • repositoryDir - The directory in which the repository should be created.
None
Back up Appian backupAppian
  • backupDir - The directory to which the files will be copied.
None
Register Environment registerEnvironment
  • environmentName - The name of the environment to register.
A repository must have been created, either through silent mode or using the menu-driven interface.
Validate Configurations validateConfigurations None
  • A repository must have been created, either through silent mode or using the menu-driven interface.
  • At least one environment must have been created, either through silent mode or using the menu-driven interface.
Deploy Configurations to Appian deployAppianConfigurations
  • environmentName - The name of the environment to deploy.
  • A repository must have been created, either through silent mode or using the menu-driven interface.
  • At least one environment must have been created, either through silent mode or using the menu-driven interface.
Encode Data Source Password encodeDataSourcePassword
  • password - The password to encode.
None
FEEDBACK