serverx-angular

ServeRX-angular

Deploy Angular applications without change and with no dependencies to serverless environments using ServeRX-ts.

• ServeRX-angular
  • Where's the Beef?
  • How to Install ServeRX-angular
    • Install serverless
    • Install ServeRX-angular
  • How to Prepare Your Angular App
    • Deployment File Contents
      • AWS Lambda Example
      • Google Cloud Functions Example
      • Settings
      • environment Setting
  • How to Deploy Your Angular App
  • How it Works

Where's the Beef?

serverless is an indispensable framework and in fact ServeRX-angular relies on it entirely to perform its deployments. Furthermore, ng-toolkit is a thorough and ingenious tool that uses Angular schematics to bake support for serverless deployments directly into an Angular app.

However, ServeRX-angular takes a different approach, with two objectives:

• Allow the serverless deployment of any Angular app, with no changes, no dependencies and in fact without the app developers having any knowledge of the eventual deployment.

• Put the experimental ServeRX-ts to the test by using it as the server-side driver.

ServeRX-angular currently supports AWS Lambda and Google Cloud Functions. Support for other providers (for example, Azure) is planned for later.

Of course, the Angular app you deploy is only the front-end half of your entire application. You will also deploy a back-end app, perhaps one that exposes a RESTful API to the front-end and perhaps one that itself is deployed serverless. The experimental ServeRX-ts could serve as the framework for this app.

How to Install ServeRX-angular

Install serverless

# Step 1. Install serverless globally
npm install serverless -g

# Step 2. Login to your serverless account
serverless login

If you don't yet have an account, you'll be prompted to sign up for one. Once you login, you'll be directed to the serverless dashboard where you'll need to create an app for each serverless Angular app that you intend to deploy.

The name you give to your app here will later be used as the service setting to ServeRX-angular.

serverless has excellent documentation on how it interacts with the providers it supports. In particular, these documents are particularly helpful:

• AWS - Credentials shows how to create an AWS account (if necessary) and store its credentials on your development computer or CI server. Once done, no additional steps are necessary, no matter how many applications you deploy.

• Setting up Google is more complex. Google - Credentials shows step-by-step how to create a Google Cloud account, a Google Cloud Project and associated service account, and how to download and store its credentials. You will need to do this for every app you deploy.

Install ServeRX-angular

# ServeRX-angular should be installed globally
npm install serverx-angular -g

How to Prepare Your Angular App

In keeping with the ServeRX-angular objectives, no special preparation of your Angular app is necessary. Instead, you just need to point to its dist directory. Typically the dist directory you need is created by running ng build --prod --aot or some variant.

Your app may be in an inner directory, whose name is the name of the app as known to the Angular CLI. In ths case, ServeRX-angular needs that inner directory, for example ./dist/hello-world.

You must also create a deployment YAML or JSON file to describe the serverless deployment of your app to ServeRX-angular. You might have different versions of this file on your development computer and your CI or build servers.

Either YAML or JSON syntax can be used, although this document uses JSON for illustration.

Deployment File Contents

Create a deployment file for your app following the examples below. You may have different deployment files in arbitrary locations on each of your development computers and CI or build servers.

AWS Lambda Example

{
  "environment": {
    "BACKEND_ENDPOINT": "https://admin.appcast.cloud"
  },
  "provider": "aws",
  "region": "us-east-1",
  "service": "serverx-angular",
  "stage": "dev",
  "domainName": "lots.washingtonnh.online",
  "certificateName": "*.washingtonnh.online"
}

Google Cloud Functions Example

{
  "credentials": "~/.gcloud/gcf-project-45679.json",
  "environment": {
    "BACKEND_ENDPOINT": "https://admin.appcast.cloud"
  },
  "project": "gcf-project-45679",
  "provider": "google",
  "region": "us-east1",
  "service": "serverx-angular",
  "stage": "dev"
}

Settings

Setting	Required?	Explanation
certificateName	Optional for AWS	The name of the certificate for a custom domain
credentials	Google only	The location of the Google credentials for this project
domainName	Optional for AWS	Custom domain name
environment	no	See below
project	Google only	The name of your Google Cloud project
provider	yes	Must be either aws or google
region	yes	The provider's region code
service	yes	TODO: Use the same name as for app
stage	Optional for Google	The provider's stage name (eg: dev)

environment Setting

The provisioning of server-side environment variables is a standard feature for all providers. In Node.js, they are typically accessed through process.env. However, your deployed Angular app does not have and does not need visibility to the server-side code, so ServeRX-angular uses this setting as follows.

This feature is experimental and included because it follows the 12 Factor principles we use at Appcast.

If you supply the environment setting, its values are inserted into your index.html as it is deployed (not in the original) and before the </head> closure like this:

<script>
  var ENV = {
    /* your settings */
  };
</script>

Front-end code can now use these settings, for example, to determine the correct back-end endpoint.

At Appcast we use an Angular service as a facade over the ENV global.

How to Deploy Your Angular App

Now all the setup is out of the way, deployment is easy. In fact, a sample Angular app and corresponding deployment settings are supplied in the sample folder of this repo.

serverx-angular --app ./dist --deploy /somewhere/else/app-name.json

It is recommended to run serverx-angular from your project's root directory. A tmp folder will be created, which you should add to your .gitignore.

Take note of the URL generated for your app. For reference, the sample app has been deployed to both AWS and Google Cloud at these URLs:

• https://gb1putt7ah.execute-api.us-east-1.amazonaws.com/dev

GCF sample https://us-east1-gcf-project-45679.cloudfunctions.net/gcf/ is not currently operational

TODO: When running in headless environments, it is possible to predict the app's URL.

How it Works

ServeRX-angular uses ServeRX-ts to host your Angular app. The AWS Lambda and Google Cloud Functions versions of the hosting code are almost identical. Here is the AWS Lambda version:

import { AWSLambdaApp } from 'serverx-ts';
import { BinaryTyper } from 'serverx-ts';
import { Compressor } from 'serverx-ts';
import { CORS } from 'serverx-ts';
import { FILE_SERVER_OPTS } from 'serverx-ts';
import { FileServer } from 'serverx-ts';
import { Route } from 'serverx-ts';

const routes: Route[] = [
  {
    path: '/',
    methods: ['GET'],
    handler: FileServer,
    middlewares: [BinaryTyper, Compressor, CORS],
    services: [{ provide: FILE_SERVER_OPTS, useValue: { root: __dirname } }]
  }
];

const awsApp = new AWSLambdaApp(routes);
export function aws(event, context) {
  return awsApp.handle(event, context);
}

See the model folder in this repo for more details.

ServeRX-angular follows these steps:

• Create a temporary directory.
• Copy your Angular app to the temporary directory, tweaking the <base> tag appropriately and adding any environment variables.
• Synthesize a serverless.yml file from your deployment file in the temporary directory.
• Install the necessary dependencies into a node_modules subdirectory using npm i --silent.
• Internally invoke the TypeScript compiler to transpile the ServeRX-ts hosting code into an index.js file in the temporary directory.
• Run serverless deploy.
• Delete the temporary directory.