GettingStarted

Getting Started

This section explains how to setup your app server using a simple example. A typical project setup is shown below.

  appdir/
    public/
      index.html
      css/
      lib/
    .env
    Dockerfile
    appenv.js
    package.json

Basic flow

1. Build your app
2. Obtain a clientid and clientsecret - see Managing clientids for instructions on how to create clientid
3. Configure the server using a combination of environment variables, env files and Dockerfile
4. Start the server with a simple command

npx @sassoftware/viya-appserverjs  --env=your-env-envfile --docker=your-Dockerfile --appenv=your-appenv.js-file

Step 1: Build your app

Use your favorite framework to build your application.

In this discussion it is assumed that all your application assets are in the public directory. This is not a requirement. Just as a convention the initial page is named index.html - use whatever is appropriate for your application

Step 2: Clientid and clientsecret

See Managing clientids for instructions on how to create clientid.

Step 3: Configure the app server

The configurations are specified using an env file and Dockerfile. The configuration is read from these files and set as environment variables. The order of processing is:

1. Dockerfile

2. env file

The standard env file is shown below with embedded notes. These values of the ENV command in the docker file are set as environment variables during initialization.

Step 3.1: Dockerfile

A typical Dockerfile looks as follows

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

# By default the server assumes you are using authorization_code flow for OAUTH
ENV AUTHFLOW=code

ENV SAMESITE=None,false

# You can specify the values in env file(see below) here
# Caution: If you build containers, do not specify anything that might be a security violation(ex: your viya server url)
# in the Dockerfile.

Step 3.2: Env file

By convention this file has an extension of env . Use this file for configurations that might change more often. After testing you might move some or all of these settings into the Dockerfile. The choice is yours.

# Viya server
VIYA_SERVER=http(s)://your-viya-server


# Get these from your administrator
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
APPPORT=8080

# APPNAME - The appserver will start at {APPHOST}:{APPPORT}/{APPNAME}
# Example: http://localhost:8080/viyaapp
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 returned from APPENV will be available as APPENV js variable in your html js
APPENV=appenv.js

# TLS Support
# see section on TLS Support for these options

Setting thru environment variables

Another option is to preset some or all of the configurations using the environment variables. A good candidate for this approach is VIYA_SERVER.

Setting application specific configurations

In a typical SAS Viya Application there is to set application specific runtime configurations. See the section on appenv

Build a placeholder appenv.js file with this content

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

Starting the server

Start the server with the following command

npx @sassoftware/viya-appserverjs  --env=./override.env --docker=./Dockerfile --appenv=./appenv.js

In the example the server will start at http://localhost:8080/viyaapp

When you visit this link you will be prompted for userid and password. On successful authentication the html listed for APPENTRY(index.html in this example) will be displayed in an authenticated browser session.

From your html you can make API calls to Viya. Below is sample javascript to get the root links for the files service using axios.

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