20 Jul 2017

Running Forge Viewer on AWS Lambda Server and API Gateway

Default blog image

    Here is a brief tutorial exposing my experience running the Forge Viewer on top of an Amazon Lambda ServerAWS Lambda is a compute service that lets you run code without provisioning or managing servers. That's basically a way to run a single function upon a trigger mechanism.

    My goal was to be able to put online a web page that displays a model loaded by the Forge Viewer, based on a Lambda server. In order to achieve that, we also need to use API Gateway in order to expose our lambda to the outside world. This tutorial assumes that you have access to an AWS account.

    1/ Lambda Server code

    Let's get started, I will use Node.js as it is my preferred back-end technology. A lambda is simply a function that may or may not take inputs from its trigger and returns a value. So I wrote a Node.js function from a basic lambda template that does the following:

  • Request a valid token from Forge
  • Reads an index.ejs file that contains the html code of my page
  • Reads an app.ejs file that contains the viewer code
  • Formats the data above by including the token in the app code and the app code in a script, then output the final result which is a valid html string that contains all the info to load our model

Here is how my lambda code looks like:

And the client code:

    2/ Create a Lambda function on AWS

Lambda function

  3/ Uploading the code

    Once you have created a Lambda function, you need to upload your code as a package: you need to upload all required dependencies along the node.js scripts, so run an npm install and zip the whole content of the directory. Do not zip the containing directory itself. Then go to the Code tab and upload your zip:

Uploading lambda package

    4/ Defining ENVIRONMENT variables

    Define the following environment variables with appropriate values: URN (URN of a previously translated model on Forge), corresponding Forge credentials FORGE_CLIENT_ID and  FORGE_CLIENT_SECRET

   5/ Testing the Lambda function

    You can test the output of your lambda function using the Test button, you should see the html output string in the console window:

lambda test output

    6/ Exposing the Lambda function to the web

    Now that our Lambda is working, we will use API Gateway to expose a public endpoint that will trigger it: got to API Gateway section in AWS and create a new API:

API Gateway

    Create a new Resource, I call it /viewer, then add a /GET endpoint:

GET resource

    Map the /GET endpoint to the Lambda function:

Mapping Lambda to the GET resource

    7/ Configuring the Endpoint

    We need to configure our endpoint a little so it's compatible with the response from the Lambda function. Edit the Integration Response so it looks as follow:

Integration response

    Then configure the Method Response as follow:

method response

    8/ Creating a Stage

    We are done with the endpoint now, but we need to create a Stage in order to expose it to the web: I create a dev stage which will show what is the public url:

stage URL

    Because our resource is named /viewer, we need to add that to the url, so our complete url is: https://ys7bat7ci2.execute-api.eu-west-1.amazonaws.com/dev/viewer. Pretty unfriendly but you can use Route 53 or any other DNS management system in order to map it to your own domain.

    Open the url in a browser et voila! The complete source of my project is available here: https://github.com/leefsmp/forge-lambda

Lambda result




Related Article

Posted By

Philippe Leefsma

I write JavaScript for the future 3D World Wide Web, A.K.A Forge Platform