SAS Viya Deployment¶

Overview¶

Data Controller for SAS Viya consists of a frontend, a set of Job Execution Services, a staging area, a Compute Context, and a database library. The library can be a SAS Base engine if desired, however this can cause contention (eg table locks) if end users are able to connect to the datasets directly, eg via Enterprise Guide or Base SAS. A database that supports concurrent access is recommended.

Prerequisites¶

System Account¶

Data Controller makes use of a system account for performing backend data updates and writing to the staging area. This needs to be provisioned in advance using the Viya admin-cli. The process is well described here: https://communities.sas.com/t5/SAS-Communities-Library/SAS-Viya-3-5-Compute-Server-Service-Accounts/ta-p/620992

Database¶

Whilst we do recommend that Data Controller configuration tables are stored in a database for concurrency reasons, it is also possible to use a BASE engine library, which is adequate if you only have a few users.

To migrate the control library to a database, first perform a regular deployment, and afterwards you can generate the DDL and update the settings file..

Make sure the system account (see above) has full read / write access.

Note

"Modify schema" privileges are not required.

Staging Directory¶

All deployments of Data Controller make use of a physical staging directory. This is used to store logs, as well as CSV and Excel files uploaded by end users. This directory should NOT be accessible by end users - only the SAS system account requires access to this directory. A typical small deployment will grow by a 5-10 mb each month. A very large enterprise customer, with 100 or more editors, might generate up to 0.5 GB or so per month, depending on the size and frequency of the Excel EUCs and CSVs being uploaded. Web modifications are restricted only to modified rows, so are typically just a few kb in size.

Deployment Diagram¶

The below areas of the SAS Viya platform are modified when deploying Data Controller:

Note

The "streaming" version of Viya uses the files API for web content, so there is no need for the web server component.

Deployment¶

Data Controller deployment is split between 2 deployment types:

Streaming (web content served from SAS Drive)
Full (web content served from dedicated web server)

There are several parts to this proces:

Create the Compute Context
Deploy Frontend (Full deploy only)
Deploy Services
First Run Configuration
Prepare the database and update settings (optional)
Update the Compute Context autoexec

1. Create Shared Compute Context¶

We strongly recommend a dedicated compute context for running Data Controller. The setup requires an Administrator account.

Log onto SASEnvironment Manager, select Contexts, View Compute Contexts, and click the Create icon.
In the New Compute Context dialog, enter the following attributes:
- Context Name
- Launcher Context
- Attribute pairs:
  - reuseServerProcesses: true
  - runServerAs: {{the account set up earlier}}
Save and exit

Note

XCMD is NOT required to use Data Controller.

2. Deploy Frontend (Full Deploy only)¶

Unzip the frontend into your chosen directory (eg /var/www/html/DataController) on the SAS Web Server. Open index.html and update the following inside dcAdapterSettings:

appLoc - this should point to the root folder on SAS Drive where you would like the Job Execution services to be created. This folder should initially, NOT exist (if it is found, the backend will not be deployed)
contextName - here you should put the name of the compute context you created in the previous step.
servertype - should be SASVIYA
debug - can stay as false for performance, but could be switched to true for debugging startup issues
useComputeApi - use true for best performance.

Updating index.html

3. Deploy Services¶

Services are deployed by running a SAS program.

Deploy Services: Streaming Deploy¶

Run the following in SAS Studio:

%let apploc=/Public/DataController; /* desired SAS Drive location */
filename dc url "https://git.datacontroller.io/dc/dc/releases/download/latest/viya.sas";
%inc dc;

Deploy Services: Full Deploy¶

Run the following in SAS Studio:

%let apploc=/Public/DataController; /* Per configuration in Step 2 above */
filename dc url "https://git.datacontroller.io/dc/dc/releases/download/latest/viya_noweb.sas";
%inc dc;

4. First Run Configuration¶

Now the services are deployed (including the service which creates the staging area) we can open the Data Controller web interface and make the necessary configurations:

First Run Configuration: Streaming Deploy¶

At the end of the SAS log from Step 3, there will be a link (YOURSAS.SERVER/SASJobExecution?_file=/YOUR/APPLOC/services/DC.html). Open this to perform the configuration - such as:

dcpath - physical path for depleyment
Admin Group - will have full access to DC
Compute Context - should be a shared compute for a multi-user deployment

First Run Configuration: Full Deploy¶

Open https://YOURSERVER/DataController (using whichever subfolder you deployed to above) using an account that has the SAS privileges to write to the appLoc location.

You will be presented with a deployment screen like the one below. Be sure to check the "Recreate Database" option and then click the "Deploy" button.

viya deploy

Your services are deployed! And the app is operational, albeit still a little sluggish, as every single request is using the APIs to fetch the content of the $(appLoc)/services/settings.sas file.

5. Deploy Database¶

If you have a lot of users, such that concurrency (locked datasets) becomes an issue, you might consider migrating the control library to a database.

The first part to this is generating the DDL (and inserts). For this, use the DDL exporter as described here. If you need a flavour of DDL that is not yet supported, contact us.

Step 2 is simply to run this DDL in your preferred database.

Step 3 is to update the library definition in the $(appLoc)/services/settings.sas file using SAS Studio.

6.Update Compute Context Autoexec¶

To improve responsiveness by another 700ms we recommend you follow these steps:

First, open the $(appLoc)/services/settings.sas file in SAS Studio, and copy the code.

Then, open SASEnvironment Manager, select Contexts, View Compute Contexts, and open the context we created earlier.

Switch to the Advanced tab and paste in the SAS code copied from SAS Studio above.

It will look similar to:

%let DC_LIBREF=DCDBVIYA;
%let DC_ADMIN_GROUP={{YOUR DC ADMIN GROUP}};
%let DC_STAGING_AREA={{YOUR DEDICATED FILE SYSTEM DRIVE}};
libname &dc_libref {{YOUR DC DATABASE}};

To explain each of these lines:

DC_LIBREF can be any valid 8 character libref.
DC_ADMIN_GROUP is the name of the group which will have unrestricted access to Data Controller
DC_STAGING_AREA should point to the location on the filesystem where the staging files and logs are be stored
The final libname statement can also be configured to point at a database instead of a BASE engine directory (contact us for DDL)

If you have additional libraries that you would like to use in Data Controller, they should also be defined here.