Overview

This is a guide for installing and running Appian in Docker containers. To learn more about containers, go to Docker's page: What Is A Container.

Containerization allows for a simplified method of installing and running Appian while ensuring a consistent environment. After following these instructions, you will have five (optionally, six) containers running the various components of the Appian software, which can be started and stopped together with a single command.

• web-application - the Appian web application
• search-server - the Appian search server
• service-manager - the Appian engines and related coordination processes
• data-server - the Appian data server
• rdbms - relational database management system
  • MySQL 5.7 is automatically downloaded as part of the Appian Docker Tools.
• web-server - (optional) Apache web server which proxies requests for the application server

Limitations

• The instructions outlined below allow you to create a single-node installation of Appian in containers running on a single machine with MySQL 5.7 as the database. Common use cases for using Appian in Docker include testing out new features and local development.
• Deploying Appian in Docker is not supported for production deployments.
• High availability and distributed installations are not supported.
• Deploying Appian in Docker is not supported for large scale deployments. Adding additional execution and analytics engines is not supported. Adding more than one machine is not supported.
• Upgrading to a new version of Appian is not supported.
• Accessing Appian in Docker with a web server is not supported.

Prerequisites

Supported operating systems:

• Windows 10
• Linux
• MacOS (experimental, running Appian on MacOS is only possible when using Docker containers)

In order to follow this guide, first download the following software and tools.

Download	Notes
Docker	Download the version appropriate for your operating system.
Docker Compose	Docker for Windows 10 and MacOS already includes Docker Compose. Linux requires this download and additional steps.
MySQL Connector/J 5.1.47	Download either the zip or the tar. If you are not using 5.1.47, you'll need to update appian-docker/build-conf/tomcatResources.xml after performing the Pre-Build Configuration steps. See the Install RDBMS Driver section for more details about changing module.xml.
Appian Installer for Linux	From the SUPPORT tab of MyAppian, click DOWNLOADS.
Appian k3 and k4 Licenses for Linux	These instructions require valid Appian license files that match the hostnames of the containers. Unless you already have both a k3 and k4 license, please request a Temporary License from Appian Support.
Appian Docker Tools 20.3-1	This zip file includes the configuration files and scripts for creating images and running the containers.

Basic installation

Docker installation

1. Install Docker for your operating system, following the instructions in the Docker Documentation.
   • Note that installing Docker on Windows 10 requires enabling the VT-x virtualization settings in BIOS and restarting the machine.
   • When using Windows, confirm that Docker has access to the C:\ drive.
   • When using Mac, confirm that Docker has access to the following directories: /Users, /Volumes, /private, /tmp. These should be shared by default.

2. In the Docker Advanced settings, set the hardware allocation:

   Use Case	CPU Minimum	Memory Minimum
   Proof-of-concept on underpowered machines (like a local laptop)	2 CPU	6 GB
   Recommended sizing per System Requirements	2 CPU	15 GB

   If the number of CPUs is later changed, the license could be invalid for the new configuration.

Pre-build configuration

In this section, you will place files and adjust configurations necessary for building the Docker images.

1. Create the base directory appian-docker.
   • Make sure that appian-docker is created inside a directory that is shared with Docker.
   • If you're using Linux, create a non-root user with the name appian. Give the appian user access to the appian-docker directory.
2. Unzip Appian_Docker_Tools.zip into appian-docker.
3. Copy the Appian Installer into appian-docker/build-files/installers.
4. In a separate directory, unzip mysql-connector-java-5.1.45.zip. Copy mysql-connector-java-5.1.45-bin.jar into appian-docker/build-files/installers.
5. (Optional) Modify the default MySQL credentials in the following files in the appian-docker/ directory. Otherwise, the Docker images will be created with a default username and password.
   • build-files/appian-rdbms/Dockerfile
   • conf/mysql-db-setup.sql
   • build-files/build-conf/tomcatResources.xml
6. Set the appian user id that Appian in Docker will use to set permissions for its files and directories:

   • Windows: In appian-docker/docker-compose.yml, under the base service, uncomment the line containing args: and the line containing APPIAN_USER_ID= and set the APPIAN_USER_ID value to 9999. See the following example configuration:

     1
     2
     3
     4
     5
     6
     7
     8
     base:
       image: appian-base
       build:
         context: ./build-files
         dockerfile: ./appian-base/Dockerfile
         args: # For dev purposes, to uniquely identify this "args" from the others in this file
           - APPIAN_USER_ID=9999
       container_name: base
     

   • Mac: From the root of appian-docker, run ./set-appian-uid-mac.sh.
   • Linux: From the root of appian-docker, run ./set-appian-uid-linux.sh.

Building Appian Docker images

1. Run the command docker-compose build from the appian-docker directory you created in the steps above.

We've now created the images necessary for running Appian in containers. Next, we will add the necessary configurations to run them.

Pre-start-up configuration

In this section, you will set up and configure files necessary for starting up the Docker containers.

1. While in the appian-docker directory, run one of the following commands:
   • Windows: set-up-initial-data.bat
   • Linux: ./set-up-initial-data-linux.sh
   • Mac: ./set-up-initial-data-mac.sh
2. Decide on the Fully Qualified Domain Name (FQDN) for the service-manager and data-server containers for use in the docker-compose.yml and appian-topology.xml files. If you already have Appian license files (k3.lic and k4.lic) tied to certain FQDNs, use the same FQDNs for the service-manager and data-server containers.
   • For example, the service-manager container FQDN is engines.example.com.
   • For example, the data-server container FQDN is dataserver.example.com.
   • A hostname is required for the search-server container in the appian-topology.xml file. A license is not required for this container. In the example appian-topology.xml file, the hostname for this container is search-server.

   The FQDN is made up of the hostname and the domain. In the example of the service-manager container, the FQDN is engines.example.com, the hostname is engines, and the domain is example.com.

3. Open appian-docker/docker-compose.yml and uncomment the 'hostname' lines, setting the desired unique FQDNs for the corresponding containers.

   1. Update hostname for the service-manager container to be the FQDN you've chosen for the service-manager container. See the following example configuration:

      1
      2
      container_name: service-manager
      hostname: engines.example.com
      

   2. Update hostname for the data-server container to be the FQDN you've chosen for the data-server container. See the following example configuration:

      1
      2
      container_name: data-server
      hostname: dataserver.example.com
      

4. Open appian-docker/docker-compose.yml and update links: for the web-application container to be the hostname you've chosen for the service-manager container. See the following example configuration:

   1
   2
   3
    container_name: web-application
    links:
      - "service-manager:engines"
   

5. Open appian-docker/docker-compose.yml and update links: for the data-server container to be the hostname you've chosen for the service-manager container. See the following example configuration:

   1
   2
   3
   4
    container_name: data-server
    hostname: dataserver.example.com
    links:
      - "service-manager:engines"
   

6. Edit the topology file appian-docker/conf/appian-topology.xml to correlate the Appian services with the containers.
   1. Set server host to the hostname of the service-manager container. For example <server host="engines">.
   2. Set search-server host to the hostname of the search-server container. For example <search-server host="search-server" port="9301"/>.
   3. Set broker host to the hostname of the service-manager container. For example <broker host="engines" port="9092"/>.
   4. Set zookeeper host to the hostname of the service-manager container. For example <zookeeper host="engines" port="2181"/>.
   5. Set data-server host to the hostname of the data-server container. For example <data-server host="dataserver" port="5400" rts-count="2"/>.
7. Change the initial system administrator user and configure any other necessary properties in passwords.properties and custom.properties and save the files in the appian-docker/conf/ directory. See Post-Install Configurations for details on properties that must be set in these files.
   • The passwords.properties file is intended to be used once, and deleted during the initial startup. Create a backup copy of this file if you ever need to perform a clean installation with no previous data.
8. Create a data-server-sec.properties file to secure the data server by following these instructions. Make sure the file is copied to the appian-docker/conf and appian-docker/data-server/conf directories.

Requesting and placing license files

Appian requires two k licenses to run. In this section you will ensure that the proper k licenses are in the correct locations.

Get FQDN for license

If you have these permanent licenses, skip to the next step. Otherwise, follow the steps below to request the k3.lic and k4.lic Appian licenses.

1. Run docker-compose up service-manager. Copy the output text to a notepad.
2. Run docker-compose up data-server. Copy the output text to a notepad.
3. Stop the containers by running docker-compose down.
4. Using the applicable output, make a license request for service-manager by following the steps in How to Request and Install Appian Product License Files.
5. Using the applicable output, make a separate license request for data-server by following the step in the above document.
6. While waiting for your permanent licenses, you may use the temporary Appian licenses for the following step. Once you receive your licenses, replace your temporary licenses with your permanent licenses.
7. Place your license files:
   1. Remove any empty directories named k3.lic and k4.lic from appian-docker/conf/service-manager-licenses/ and appian-docker/conf/data-server-licenses/.
   2. Place the k3.lic file from the service-manager request (or your existing k3.lic) into appian-docker/conf/service-manager-licenses.
   3. Place the k4.lic file from the data-server request (or your existing k4.lic) into appian-docker/conf/data-server-licenses.
8. Update the appian-docker/docker-compose.yml file to use the license files:
   1. To use the k3.lic license, uncomment - ./conf/service-manager-licenses/k3.lic:${APPIAN_HOME}/server/_bin/k/linux64/k3.lic.
   2. To use the k4.lic license, uncomment - ./conf/data-server-licenses/k4.lic:${APPIAN_HOME}/data-server/engine/bin/q/l64/k4.lic.

Now you are ready to start your containers!

Starting and stopping Appian in containers

1. In the appian-docker directory, run docker-compose up -d.
   • To view start up progress of any container: docker-compose logs -f <CONTAINER_NAME>
2. Once the logs indicate that the web application is up, access Appian through browser.
   1. The logs will indicate that the web application is up by printing out: org.apache.catalina.startup.Catalina.start Server startup in…
   2. On the local machine, open a browser and navigate to http://localhost:8080/suite
      • Note: the web application will wait until the other services are running to start up, so if it is running, it means everything else is too.
3. To stop and remove the containers, run docker-compose down
   • This command will shut down the containers gracefully; it will not cause any data to be lost.

To operate with an optional web server, follow the configuration steps in the following section. This can be useful if you want to run Appian using the https scheme.

Congratulations! You have successfully implemented Appian in Docker!