Introduction

The RAP 3 Docker server is a Docker compose stack consisting of between two and four containers, depending on deployment options. This deploys the RAP 3 server-side components. 

The server components in RAP 3 consist of: 

• RAP UI
• API Server
• MySQL Database
• Workflow Engine

Additionally, the stack can be configured with a built-in reverse proxy to route requests through to the API Server and RAP UI containers via a single URL. 

Including the MySQL database in the stack is optional – making it possible to connect to an existing database outside of the stack.

The same is true also for the License Server, whereby you can use an internal (to the stack) instance or an alternative License Server instance outside of the RAP docker stack.

System Requirements 

Although it is possible to configure RAP 3 for Docker under Windows, it is more likely that deployment will be in a Linux environment, and this document assumes that to be the case. The stack has been tested with the following components, which are prerequisites for installation: 

• Docker: 20.10.2+
• Docker-compose: 1.26.0+

Installation should work with more recent versions, but will likely not work with older ones. 

Contents

Within the supplied tar file root directory, you will find the start scripts to run the docker stack.
The package also contains two directories: 

docker – Contains the .yml scripts for various configurations options. The key file in this directory is “docker.env”; this contains all of the configuration settings.

proxy – Contains docker files and config for running a reverse proxy for routing requests to running servers. This is most often required when routing requests to a server from an external network (including the Internet) or when setting up a multi-tenancy server. 

Getting Started

There are two primary ways to start a RAP server.

Demo Mode

Running the script "startdemo" in a Linux terminal will start a complete and self-contained server, useful for demo purposes. This instance of RAP can only be accessed from "localhost" and as such, is not suitable for running on a headless server without further configuration steps for setting up a reverse proxy. This mode is mostly intended for rapid creation of scratch environments for demo purposes, accessed from a local desktop session.

Instance Mode

Running the script "startinstance" in a Linux terminal will start a RAP server in instance mode, which is subject to settings in a primary configuration file (docker.env) and command line options.

These settings primarily affect two aspects of execution:

Database Location

RAP3 uses a MySQL database. You can choose between using a fully encapsulated database held within the RAP docker stack, or connect to a database elsewhere on your network. 

When hosting a database on a local database server, you will need to create the database and assign some permissions before starting the RAP services; usually by logging into a MySQL session using either the MySQL command line client, or a desktop client such as MySQL Workbench, and then running the following commands:

create database MyRAPDatabase;

create user MyRAPUser identified by 'SomePassword';

grant all on MyRAPDatabase.* to 'MyRAPUser'@'networklocation';

flush privileges;

where "networklocation" is a pattern that restricts where that user can access MySQL from. For RAP, we would generally recommend using a subnet pattern such as '192.168.1.%' to limit access to the local network only.

Network accessibility

The RAP Docker Suite exposes two services; an API server and a client UI (the 'Portal'). It's possible to access these directly through a browser, via 'localhost' - but in this instance, you can only connect to the services from the same host running the suite. If you need to access the suite from other locations on the network, we recommend you run the suite in proxy mode. In this case, the suite includes a proxy server which will forward requests from remote browsers to the relevant service in the server, via a single URL endpoint.

Configuration

Open the /docker/docker.env file in a text editor and, following the contained hints in the env file, set the variables according to how you wish run the application.

The docker.env includes the following settings:

• File/data storage
• Proxy config
• Database connections
• Access URL and port configuration
• RAP License and License Server details
• SMTP settings for email notifications
• Docker container references

Data Persistence

There are two environment variables that determine where files that are external to the docker containers are stored; LOCALFILES and SITEFILES. As default these are both set to the same value ~/.rap.

• LOCALFILES: This is used by the internal DB server as the location of the MySQL database control files. This ensures that data stored in the database is persisted if/when the docker containers are restarted. This is also the location where the proxy server expects to be able to find SSL certificates if needed.
  SITEFILES: This is used by the API server to store RAP Workitem payloads and execution reports.

Setting Up SSL

To set up a RAP Server with SSL support, you will need to use a RAP Server configuration that includes a reverse proxy to host the SSL endpoint.
The certificates will need to be set up for the correct domain, and requests to this url need to be correctly routed to the server running the RAP 3 Docker package. Self-signed certificates can be used, but may cause errors in browsers that have not been set to trust the local signing authority.
The docker package is supplied with a sample proxy.conf file for nginx that supports an SSL endpoint. The SSL certificate and key need to be placed in a folder ‘nginx/certs’ at the location where the variable LOCALFILES is pointing (this is set in the main docker.env file for the instance - as above).
You need to ensure the server name in the proxy.conf file matches that for which the certificate is valid.

Startup

Once you have set the configuration as desired, the suite should be started using the “startinstance” script.

The “startdemo” script bypasses many options set in the configuration file to initiate a sandboxed environment that can only be accessed from the localhost and uses an encapsulated database (see above).

Starting an Instance 

The startinstance script has the following command line: 

startinstance [-p] [-r] -f <environmentfile> -p <instancename> 

• -p: Include the -p argument if you are creating an instance with an internal proxy server. The default when omitting this argument is to start an instance with no proxying. 
• -r: Include the -r argument if you are starting an instance that connects to a remote MySQL server, rather than one within this docker stack.
• -f <envfile>: Path and filename of the environment file to use. Each instance requires its own separate environment file. By default, this uses docker.env in the docker directory.
• -p <instance name>: Each instance of the RAP Server runs between two and five containers (depending on configuration) in a self-contained environment. To help administration of multiple instances of the server, each instance requires a name.

Access

Once running, the portal UI and the API can both be accessed via a URL. The makeup of this URL will vary depending on the mode in which the suite is running and where you are connecting from, for example:

| Mode                      | Access URLs                                                                                                  |
|----------------------|----------------------------------------------------------------------------------|
| localhost                 | UI: http://localhost:8181  API: http://localhost:5000                                    |
| local with proxy      | UI: http://yourhost API: http://yourhost/rap                                                |
| external with proxy | UI: https://yourhost.example.com API: https://yourhost.example.com/rap |