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 on the JBoss application server. JBoss is the only application server handled by the configure script at this time, however the deployment of configurations to Appian will work regardless of which application server you use. See System Requirements for the supported version of JBoss.

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.

If you had previously used Appian Configuration Manager for this purpose, see the Configuration Manager to Configure Script Migration Guide.

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 prerequisite software (application server, RDBMS, etc.).
  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 either JBoss, Appian, or both.

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. The following directories contain configuration files and are backed up when using this menu option:

  • <APPIAN_HOME>/ear/suite.ear
  • <APPIAN_HOME>/search-server/

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.

The one exception to this rule is that during deployment the script will set the value of APPIAN_HOME_EAR in JBoss' standalone.conf based on the directory from which the configure script is run. To override this behavior you can replace the string of @appian-ear.path@ with the desired path.

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 k.lic.env file placed in <REPO>/server/_bin/k/linux64/ will be copied to the corresponding directory in <APPIAN_HOME> when the env environment is deployed.
  • Creating a com/mysql/jdbc/main subdirectory of the <REPO>/bin/jboss/jboss-eap-<ver>/modules directory and adding the MySQL driver jar and module.xml to it will cause that directory and contents to be copied to the corresponding directory in <JBOSS_HOME>

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 and JBoss directories.

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 either Appian, JBoss, or Both
  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.

The script will prompt you to enter the location of the JBoss directory if you haven't already and will remember that directory the next time you run the script. You can make the configure script forget the JBoss directory location by editing the .configure file in <APPIAN_HOME>/_admin/_scripts/configure and removing the line that starts with jboss.path.

If multiple versions of JBoss are supported by the version of Appian you are running, you will be prompted to select which version to deploy.

Tools

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

Encoding passwords for use in JBoss data source configurations

  1. Run configure.sh (or configure.bat on Windows)
  2. From the main menu, select 6 - Tools
  3. Select 1 - Encode password for JBoss Security Domain
  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 in JBoss.

See also: Configuring JBoss

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:

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.
Deploy Configurations to JBoss deployJBossConfigurations
  • environmentName - The name of the environment to deploy.
  • jbossDir - The JBoss home directory to which the configurations will be deployed.
  • jbossVersion - The version of JBoss.
  • 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 JBoss Security Domain Password encodeSecurityDomainPassword
  • password - The password to encode.
  • jbossDir - The JBoss home directory.
None
FEEDBACK