Skip to content

Instantly share code, notes, and snippets.

@brianneisler

brianneisler/initial-setup.md

Last active July 30, 2018 16:39
Show Gist options
  • Save brianneisler/8ee1cbc9c77e7ac145592a0cff121015 to your computer and use it in GitHub Desktop.
Save brianneisler/8ee1cbc9c77e7ac145592a0cff121015 to your computer and use it in GitHub Desktop.
Download ZIP
Workshop - Setting Up the Serverless Framework
Raw
initial-setup.md

Initial Setup

End Results

  • Should have node 8.11.3 or later installed
  • Should have a new AWS IAM User with full admin privileges
  • Should have a text editor installed
  • Should have the serverless framework installed
  • Should have your AWS credentials configured in serverless

Install node js and NPM

$ node -v
v8.11.3
  • You should also be able to run npm -v from your command line and should see...
$ npm -v
5.6.0

Setup an AWS Account and Create an Administrator User

Sign up for AWS

  • If you already have an AWS account, skip to the next task. If you don't have an AWS account, use the following procedure to create one.
  • To create an AWS account
    1. Open https://aws.amazon.com/, and then choose Create an AWS Account.
    2. Follow the online instructions.
    • Part of the sign-up procedure involves receiving a phone call and entering a PIN using the phone keypad.
  • Note your AWS account ID, because you'll need it for the next task.

Create an IAM User

Services in AWS, such as AWS Lambda, require that you provide credentials when you access them, so that the service can determine whether you have permissions to access the resources owned by that service. The console requires your password. You can create access keys for your AWS account to access the AWS CLI or API. However, AWS doesn't recommend that you access AWS using the credentials for your AWS account. Instead, they recommend that you use AWS Identity and Access Management (IAM). Create an IAM user, add the user to an IAM group with administrative permissions, and then grant administrative permissions to the IAM user that you created. You can then access AWS using a special URL and that IAM user's credentials.

If you signed up for AWS, but you haven't created an IAM user for yourself, you can create one using the IAM console.

This workshop assumes you have a user (adminuser) with administrator privileges. When you follow the procedure, create a user with name adminuser.

  • To create an IAM user for yourself and add the user to an Administrators group
    1. Sign in to the Identity and Access Management (IAM) console at https://console.aws.amazon.com/iam/.
    2. In the navigation pane, choose Users, and then choose Add user.
    3. For User name, type a user name, adminuser.
    4. Select the check boxes next to Programmatic access and AWS Management Console access
    5. Select Custom password, and then type the new user's password in the text box.
    • Note down your username and password for later use.
    1. Unselect the check box next to Require password reset.
    2. Choose Next: Permissions.
    3. On the Set permissions for user page, choose Add user to group.
    4. Choose Create group.
    5. In the Create group dialog box, type the name admins for the new group.
    6. For Filter, choose Job function.
    7. In the policy list, select the check box for AdministratorAccess.
    8. Now choose Create group.
    9. Back in the list of groups, ensure the check box is selected for your new group. Choose Refresh if necessary to see the group in the list.
    10. Choose Next: Review to see the list of group memberships to be added to the new user. When you are ready to proceed, choose Create user.
  • Note down the following from the Success page
    • name of your IAM user
    • AWS Access key ID
    • AWS Secret access key

Install a Text Editor

Install Serverless Framework

  • Run this command in CLI
npm install -g serverless
  • After install is complete, you should be able to run serverless -v from your command line and get a result like this...
$ serverless -v
1.29.0

Configure your AWS Credential for Serverless Framework

  • Run this command in the command line to configure your AWS provider credentials
serverless config credentials -p aws -k [Your AWS Access Key ID] -s [Your AWS Secret Access Key]

Login to the Serverless Platform

  • Run this command to login/signup on the Serverless Platform
$ serverless login

Create an application

  • In the Serverless Dashboard, create an app called "myapp-dev"
Raw
workshop.md

Workshop - Setting Up the Serverless Framework

Hello World from Scratch

Goals

  • Create a working Serverless app with a hello function from scratch
  • Learn how to deploy Serverless apps
  • Learn basic anatomy of a Serverless project
  • Learn how to invoke serverless functions from command line

Creating a Project from Scratch

  • Create a project from scratch using a template to get started in your language/provider of choice.
  • To see a list of available templates, simply...
serverless create --help
  • Using the aws-nodejs template...
serverless create --template aws-nodejs --path hello-world
  • Project created!

Deploying Project

  • Project default is deployable
  • Easy to deploy a project
cd hello-world
serverless deploy
  • This will package up your project and send it to AWS for deployment through Cloud Formation
  • Anytime you make a change and want to test, simply redeploy

Anatomy of a Serverless Project

  • Open project in text editor
atom .
  • Project files
serverless.yml
handler.js
.npmignore

serverless.yml

  • Contains the configuration of your serverless app
  • Review basic serverless yaml properties
    • service - name of service you are Deploying
    • provider - config of which provider you are deploying to...
    • functions - serverless apps are composed of one or more functions that can be connected to multiple events (more on that later...)
      • [function_name]: [path_to_function_file].[function_property_path]

handler.js

  • This is where the code of our serverless functions live

.npmignore

  • simple config of npm to prevent .serverless folder from being packaged in to project.

Invoking a Deployed function

  • Functions that have been deployed to AWS can be invoked using the command line. Easy way of testing your functions while you work on them...
serverless invoke -f hello

Hello World is boring... Let's make a dynamic web page!

cd ..

A dynamic http Page

Goals

  • Illustrate how to hookup an API Gateway endpoint to a Lambda function to render HTML on a GET request.
  • Learn some basics of event driven application design.

References

Create a new project

  • Create another new project.. different name
serverless create --template aws-nodejs --path dynamic-html

Serverless is about events!

  • All serverless apps are designed to be event driven.
  • We are tying serverless functions to events as handlers.
  • http is an event! Lambda Web App Reference Architecture
  • Tying events to functions is easy
functions:
  [function_name]:
    handler: [path_to_function_file].[function_property_path]
    events:
      - [event_type]:
          [event_arg_name]: [arg_value]

Add dynamic content and wire up events

  • Open project in editor
cd dynamic-html
atom .
  • Modify serverless.yml
service: dynamic-html

provider:
  name: aws
  runtime: nodejs4.3

functions:
  landingPage:
    handler: handler.landingPage
    events:
      - http:
          method: get
          path: landing-page
  • Modify handler.js
'use strict';

module.exports.landingPage = (event, context, callback) => {
  let dynamicHtml = '<p>Hey Unknown!</p>';
  // check for GET params and use if available
  if (event.queryStringParameters && event.queryStringParameters.name) {
    dynamicHtml = `<p>Hey ${event.queryStringParameters.name}!</p>`;
  }

  const html = `
  <html>
    <style>
      h1 { color: #73757d; }
    </style>
    <body>
      <h1>Landing Page</h1>
      ${dynamicHtml}
    </body>
  </html>`;

  const response = {
    statusCode: 200,
    headers: {
      'Content-Type': 'text/html',
    },
    body: html,
  };

  // callback is sending HTML back
  callback(null, response);
};

Deploy Project

serverless deploy
  • This will setup your lambda functions AND your API Gateway!
  • When done you should see something like this...
Serverless: Stack update finished...
Service Information
service: dynamic-html
stage: dev
region: us-east-1
api keys:
  None
endpoints:
  GET - https://88uork48ri.execute-api.us-east-1.amazonaws.com/dev/landing-page
functions:
  dynamic-html-dev-landingPage

Open our http endpoint

  • get the url from the endpoints section in the output
  • open url in browser https://88uork48ri.execute-api.us-east-1.amazonaws.com/dev/landing-page
  • Add name to url https://88uork48ri.execute-api.us-east-1.amazonaws.com/dev/landing-page?name=Brian

Hello Name is boring... Let's have some fun!

cd ..

Start from Any Example

  • install and get started with any example from github

Goals

  • Illustrate how to use a reference architecture as a starting point.
  • Experiment with new things.

References

  • You can find the examples here https://github.com/serverless/examples

Create a New Project from Example

serverless install --url https://github.com/serverless/examples/tree/master/aws-node-rest-api-with-dynamodb
  • When done you should see something like this...
Serverless: Downloading and installing "aws-node-rest-api-with-dynamodb"...
Serverless: Successfully installed "aws-node-rest-api-with-dynamodb"

Usually Different Setup Required per Example

There Are Lots of Examples

  • Multiple events...
  • Multiple providers...
  • Multiple Languages...
  • More being added regularly!
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment