Docker Instructions

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: 

  • API Server
  • MySQL Database
  • Console/Dashboard UI
  • Workflow Engine

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

Including the MySQL database in the stack is optional – making it possible to make a connection 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 testing with the following components, which are prerequisites for installation: 

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

A working installation should work with more recent versions, but will likely not work with older ones. 

Getting Started 

Unpack the supplied tar.gz file to a suitable location. 

The installation consists of three directories: 

docker – Contains the .yml scripts for various configurations of server. The key file in this directory is “docker.env”; this contains all the configuration settings. The default settings as shipped, are to create a completely local, standalone server that can be used from localhost only. 

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. 

scripts – Contains shell scripts for starting various configurations of servers. 

The simplest method for starting a clean server instance after unpacking the install file is: 

  1. Open a terminal window and run "docker login", entering credentials which provide access to the tplan docker repo's
  2. Navigate to scripts/demo 
  3. Run the script ./startdemo
  4. Once the server is running, open a browser and navigate to http://localhost:5100 and "Initialize" the License Server database
  5. Once initialized you will need to enter your provided License Server license into the displayed field
  6. Then log into the License Server using the credentials indicated, open the "RAP Licenses" blade and Add License before again entering your provided RAP license
  7. Navigate to http://localhost:8181 and initialize the RAP database (this will redirect you to the RAP Admin console)
  8. Finally navigate to back to the main RAP URL - http://localhost:8181 and logon as SysAdmin/sysadmin1

Configuration 

Out of the box, the default configuration will create a full RAP instance and License Server running on localhost only. This is useful for quick demos, or simply the fastest possible way to run up a RAP Server. It is of limited use as it won’t work from any context other than “localhost”. 

Instancing

Beyond the simple local instance so far described, the RAP 3 Docker Deployment options cover several common use-cases, from a single intranet-addressable instance, through to multi-tenancy stacking accessible via SSL from the internet. 

This flexibility is achieved through leveraging multiple instance configuration files and reverse proxying. 

The “startdemo” script used to run the local demo above exercises the most simple configuration, and as such should not be used for production deployment. In production, you will need to use the “startinstance” script in the “scripts/multi” directory. 

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 a built-in DB. This is useful if you have existing MySQL DB infrastructure you would like to use instead of the default built-in instance. 
  • -f <envfile>: Path and filename of the environment file to use. Each instance requires its own separate environment file. 
  • -p <instance name>: Each instance of the RAP Server runs between two and five containers (depending on configuration) in a self-contained environment. To make administration of multiple instances of the server, each instance requires a name. 

Intranet accessible 

Use case: A server is required that is accessible to devices on the same local addressable network (local LAN, VPN circuit). 

Edit the docker.env file in the docker directory, and change the following settings: 

  • RAPAPIURL – Change this so that the host name in the URL matches that of the server host. If DNS is available on the network, use the canonical name, otherwise an IP address can be used but make sure this is a static address that won’t change. 

Eg: http://testserver:5000/api/v3/api 

By default, the API server listens on port 5000 so this is included in the URL. 

Save the docker.env file, then navigate to scripts/multi and start the instance with the following command line: 

startinstance -f ../../docker/docker.env  -p testserver 

This will create a new instance of the RAP server that’s addressable from the local network. 

You will notice in this example, you still have to address the Portal UI and Server Console using their port numbers. This can be avoided by using an internal proxy. 

Simple Internal Proxy 

If you are configuring a single instance for local access, it can be helpful to expose the server as a single URL. As there are two services running in the RAP Server, this means we need to add a proxy server to handle the requests to each service.

Create a new directory call “instances”. Now create a directory in there with the name of the instance you want to create – here we’ll just call it “test”.

Make a copy of the docker.env file in the docker folder and place it in the new test folder you just created.

Now edit the docker.env file and make the following changes:

  • LOCALFILES=’[INSTALLEDFILESLOCATION]/instances/test/.rap’
  • SITEFILES=’[INSTALLEDFILESLOCATION]/instances/test’
  • PROXYCONFIGS= ’[INSTALLEDFILESLOCATION]/proxy/locations’
  • RAPAPIURL=’http://YOURPCHOSTNAME/rap/api/v3/rap
  • RAPSERVERPATH=’/rap’

Save this, and then edit the default.conf file in the proxy/locations folder. You need to set the hostname in each “proxy_pass” directive to the PC hostname. Save this change.

Now edit the proxy.conf file in the proxy folder, and set the server name to the Host PC name. Save this.

You can now start the instance by running startinstance like this:

startinstance -p -f [INSTALLEDFILESLOCATION]/instances/test/docker.env  -p test

This will start the instance, and you can access the main ui at:

http://HOSTNAME/

and the API Server

http://HOSTNAME/rap

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).
You need to ensure the server name in the proxy.conf file matches that for which the certificate is valid, so for the domain example.com, you would need a proxy.conf file like this:
events {

}

http {
  error_log /etc/nginx/error_log.log warn;
  client_max_body_size 20m;
  
  proxy_cache_path /etc/nginx/cache keys_zone=one:500m max_size=1000m;

  upstream apihost {
    server apiserver:5000;
  }

  server {
    server_name example.com;

    listen 80;
    listen 443 ssl;
    ssl_certificate /etc/ssl/private/fullchain.pem;
    ssl_certificate_key /etc/ssl/private/privkey.pem;

    location / {
        proxy_pass        http://portal:80;
        proxy_set_header  X-Forwarded-For $remote_addr;
    }

    location /rap/ {
        proxy_pass http://apihost/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $server_name;
    }
  }
}

This instance’s URLs would be https://example.com (for the Portal UI) and https://example.com/rap for the Admin UI/API server.

Data Persistence

There are two environment variables that determine where files that are external to the docker containers are stored; LOCALFILES and SITEFILES. In the default demo setup, 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 workitem packages and reports.