Skip to content

Orchestrator

Installation

Orchestrator can be installed on any RPM-based Linux distribution. The rpm package provides static web assets that are served up and rendered via a Nginx reverse proxy.

RPM Installation

To start, either obtain a rpm package file from Dispersive or set up the Dispersive JFrog yum repository for 4.3.0. Tim Smith or Scottie Higgins can help set up JFrog for your organization.

If you have a physical rpm file, run the following (replacing the rpm filename with your actual filename):

yum install -y epel-release
yum install -y nginx
rpm -ivh ./dvn-orchestrator-4.3.0.00216-1.el7.x86_64.rpm

If you are connected to the yum repository, run the following:

yum install -y epel-release
yum install dvn-orchestrator

As a dependency, yum will automatically install the Nginx software as well (provided you already have epel-release installed, which makes the nginx package available for install).

RPM File List

/etc/nginx/templates/default.conf.template
/etc/nginx/templates/nginx.conf
/usr/share/nginx/certificates
/usr/share/nginx/certificates/root-ca.pem
/usr/share/nginx/certificates/server-cert.pem
/usr/share/nginx/certificates/server-key.pem
/usr/share/nginx/html/dispersive
/usr/share/nginx/html/dispersive/asset-manifest.json
/usr/share/nginx/html/dispersive/favicon.ico
/usr/share/nginx/html/dispersive/index.html
/usr/share/nginx/html/dispersive/logo192.png
/usr/share/nginx/html/dispersive/logo512.png
/usr/share/nginx/html/dispersive/manifest.json
/usr/share/nginx/html/dispersive/robots.txt
/usr/share/nginx/html/dispersive/static
/usr/share/nginx/html/dispersive/static/<-- more files in this subdirectory

The static subdirectory contains the output of the React build operation. These files have arbitrarily hashed names, which may change between installations. They will not need to be accessed directly, so the names and content aren't critical to list in this document.

File or Directory Purpose
default.conf.template template for the DVN-specific Nginx site configuration
nginx.conf template for the main Nginx configuration
/usr/share/nginx/certificates TLS certificates for the site

Configuring the Web App

The Nginx reverse proxy will act to not only serve up the static web assets for the application, but to proxy 2 different kind of requests to the proper location:

  • direct API calls -> service-prov

  • tunneled API calls -> service-prov (which will then reach out to the respective controller and VTC to serve content)

Configuring Nginx

Start by copying the site configuration template to the location were Nginx will read and utilize it. Nginx will load all of the conf files inside of the /etc/nginx/conf.d directory upon startup.

cp /etc/nginx/templates/default.conf.template /etc/nginx/conf.d/default.conf

Open up the file you just copied and replace the placeholder service-prov host/port with the actual values:

  • SERVICE_PROV_HOST is the IP address/hostname of your service-prov server
  • SERVICE_PROV_PORT is the port your service-prov server is listening on

Note that if your Nginx instance is on the same machine as the service-prov API, you can use 127.0.0.1 as the value for the host.

Example, change this:

upstream backend {
    server ${SERVICE_PROV_HOST}:${SERVICE_PROV_PORT};
}

to this (assuming that service-prov is listening on port 3004, update the port according to your configuration):

upstream backend {
    server 127.0.0.1:3004;
}

Finally, copy the main Nginx configuration file to its proper location:

cp /etc/nginx/templates/nginx.conf /etc/nginx/nginx.conf

No modifications are needed to this file, if you want to use the default settings (which would start the server and listen for HTTPS connections on port 443). See the Notes section below for additional customization.

Running Orchestrator

Running Orchestrator essentially means running the reverse proxy server. Therefore, all systemd commands will be directed towards the Nginx service:

systemctl start nginx # start the service
systemctl stop nginx # stop the service
systemctl restart nginx # restart the service
systemctl enable nginx # enable upon reboot

Logs

You can use tools like journalctl to view the output of Nginx. However, there are no useful logs to this application. Most of the information you'd be looking for could be found in the javascript web console of the browser of the logs of service-prov.

Updating Orchestrator

Updating Orchestrator is very simple. The RPM package will automatically pull the new web assets into the proper location, and Nginx will automatically start serving these assets without any additional commands.

From a physical package file (replace filename here with your actual file):

rpm -Uhv ./dvn-orchestrator-4.3.0.00216-1.el7.x86_64.rpm

Using the yum repository:

# update cache first, and then:
yum update dvn-orchestrator

Note that if you make and changes to the Nginx configuration files, you'll need to run systemctl restart nginx to see those changes take effect.

Notes

Custom Certificates

Our Orchestrator package comes with default development SSl certs. To replace these with valid or custom certificates, run the following commands:

cd /usr/share/nginx/certificates
mv </path/to/your/cert> server-cert.pem
mv </path/to/your/key> server-key.pem

Note that when you move in your files they must keep the names server-cert.pem and server-key.pem for the reverse proxy to recognize them.

Firewalls and Ports

On the machine running Nginx and Orchestrator, it will be necessary to open up incoming connections to the web server. By default, the server is configured to listen on port 443.

Additionally, the reverse proxy needs to be able to communicate with service-prov. If this is running on the same machine, there are no concerns. If the API is running on a different machine, then open up the requisite port on that machine (remember, service-prov defaults to listening on port 3004 unless it has been customized).

Listening on a Custom Port

Orchestrator comes with Nginx files configured to listen on port 443. If something else is already listening on that port or you want to use a different port for any reason, the changes needed are simple.

Edit the site configuration file. Near the top of the file there is a server configuration block. Find the 2 listen configuration lines and update them with the new desired port (this will update the listener for both IPv4 and IPv6).

Example: Open /etc/nginx/conf.d/default.conf and change this:

listen       443 ssl http2;
listen  [::]:443 ssl http2 ipv6only=on;

to this

listen       8000 ssl http2;
listen  [::]:8000 ssl http2 ipv6only=on;

To make these changes take effect, restart Nginx:

systemctl restart nginx

SELinux

If Orchestrator is installed on a SELinux-enabled OS, certain additional steps must be taken to allow for proper functionality. For example, in order to proxy requests to the API, the SELinux settings must be adjusted to allow for that additional functionality:

sudo semanage port -a -t http_port_t -p tcp 3004 # here 3004 is the port that service-prov is listening on

The administrator could also fix this by setting SELinux to permissive instead of enforcing.

In order to listen on a custom port (aka not 443 or 80), additional SELinux changes might need to be made as well. Full documentation of these issues can be found in this NGinx blog post.