Rapid Web Application deployment using @SASSoftware/restaf-server

2 Likes

In my previous article I discussed a couple useful tools for deploying SAS Viya Applications. This article discusses the restaf-server app server, designed for rapid development and deployment of SAS Viya applications. Using a couple of configurations files, you can deploy an application with standard SAS Viya authentication and access to all SAS Viya services using REST APIs.

The key features of this app server are:

authentication
serve up static content
extendable with custom routes
TLS support

restaf-server uses hapijs to do all the heavy lifting and takes advantage of its great configurability.

The complete restaf-server documentation and code are available in GitHub.

Basic Steps

build your web application(s)
obtain a ClientID and Clientsecret
configure the server using a combination of
- env files
- Docker file
- environment variables
create appenv.js for application specific configurations
start the server with a simple command (see below for an example)

npx @sassoftware/restaf-server --env=your-env-env-file --docker=your-Dockerfile --appenv=your-appenv.js-file

Typical flow

Once the server is started the applications flows as shown below. The sequence of steps is numbered.

Quick start example

Let us assume your application directory structure is along the lines of:

appdir/

public/

index.html

override.env

Dockerfile

appenv.js

package.json

Step 1: Create your application

Create your web application using any framework. This article assumes that the artifacts of your application are in the public directory but that is purely a personal choice.

Step 2: Create clientid and clientsecret

Obtain the clientid and clientsecret from your system administrator. If you are the administrator see Managing clientids page on GitHub for instructions on how to create this.

Step 3.1: Create the env file

This file (along with Dockerfile) is used to configure the app server. Create a file with a .env extension. In this example override.env is the name of this file. Below is an example of override.env.

VIYA_SERVER=http://your-viya-server

# OAUTHFLOW -  clientid - code|implicit
AUTHFLOW=code

# Get these from your administrator. Sample value shown below
CLIENTID=appc
CLIENTSECRET=secret

# Where the app server is running:
# Valid values:
#     localhost
#     http(s)://hostname
#     http(s)://ip address
# When running in docker do not specify this.
APPHOST=localhost

# PORT for app server. Pick a port of your choice
APPPORT=8080

# APPNAME – A user friendly name for your application
# The appserver will start at {APPHOST}:{APPPORT}/{APPNAME}
APPNAME=viyaapp

# Location of assets
# All assets are located relative to APPLOC
APPLOC=./public

# Main entry of your app
# On successful authentication this entry will be displayed in the browser
APPENTRY=index.html

# The JS object is available as APPENV js variable in your app.
# Include the following script tag in your html
# <script src=”/{APPNAME}/appenv”></script>
APPENV=appenv.js

# TLS Support
# see documentation on TLS Support

Step 3.2: Create the Dockerfile

A typical Dockerfile for this example appears below. This is the Dockerfile you will use if your application is delivered via docker containers.

FROM node:12.16.1-alpine
LABEL maintainer="your-email"
WORKDIR /usr/src/app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 8080
ENV APPHOST=0.0.0.0
ENV SAMESITE=None,false
ENV KEEPALIVE=YES

Step 4: Create Application Specific configuration file

In a typical SAS Viya Application, this file configures items like default caslibs, tables, reports, etc., for the application. See more details and an example in the viya-optimization-apps GitHub repository.

Build a placeholder appenv.js file with this content:

let x= {hi: 'hi there'};
return x;

You then start the server with the following command:

npx @sassoftware/restaf-server  --env=./override.env --docker=./Dockerfile --appenv=./appenv.js

In the current example, the server will start at http://localhost:8080/viyaapp (http:{APPHOST}:{APPPORT}/APPNAME).

When you visit this link, SAS prompts you for user id and password. On successful authentication the html listed for APPENTRY (index.html in this example) displays in an authenticated browser session.

From your html you can make API calls to SAS Viya. Below is sample JavaScript code to get the root links for the files service using axios (note the host is the url for the Viya server).

async function makeViyaCall () {
            let config = {
                url         : host + '/files/',
                method      : 'GET',
                withCredentials: true,
                headers     : {
                    'accept':'application/json,application/vnd.sas.api+json',
                }
            };
            let r = await axios(config);
            return r.data;
        };

Finally

With a few building materials and configuration values you can deploy your application easily and quickly. Feel free to clone and adopt this code as you see fit. Comments and contributions are welcome.

Cheers…