Update README with info for changing AWS profile (dherault#380)

As commented in dherault#195 we should reflect that AWS profile can only
be changed by env variable.

Author: jacintoArias

README.md

@@ -1,4 +1,5 @@
 # Serverless Offline Plugin
+
 [![serverless](http://public.serverless.com/badges/v3.svg)](http://www.serverless.com)
 [![npm version](https://badge.fury.io/js/serverless-offline.svg)](https://badge.fury.io/js/serverless-offline)
 [![Build Status](https://travis-ci.org/dherault/serverless-offline.svg?branch=master)](https://travis-ci.org/dherault/serverless-offline)
@@ -18,28 +19,29 @@ This [Serverless](https://github.com/serverless/serverless) plugin emulates AWS
 To do so, it starts an HTTP server that handles the request's lifecycle like APIG does and invokes your handlers.
 
 **Features:**
-- Nodejs λ only.
-- Velocity templates support.
-- Lazy loading of your files with require cache invalidation: no need for a reloading tool like Nodemon.
-- And more: integrations, authorizers, proxies, timeouts, responseParameters, HTTPS, Babel runtime, CORS, etc...
+
+* Nodejs λ only.
+* Velocity templates support.
+* Lazy loading of your files with require cache invalidation: no need for a reloading tool like Nodemon.
+* And more: integrations, authorizers, proxies, timeouts, responseParameters, HTTPS, Babel runtime, CORS, etc...
 
 This plugin is updated by its users, I just do maintenance and ensure that PRs are relevant to the community. In other words, if you [find a bug or want a new feature](https://github.com/dherault/serverless-offline/issues), please help us by becoming one of the [contributors](https://github.com/dherault/serverless-offline/graphs/contributors) :v: ! See the [contributing section](#contributing).
 
 ## Documentation
 
-- [Installation](#installation)
-- [Usage and command line options](#usage-and-command-line-options)
-- [Usage with Babel](#usage-with-babel)
-- [Token authorizers](#token-authorizers)
-- [Custom authorizers](#custom-authorizers)
-- [AWS API Gateway features](#aws-api-gateway-features)
-- [Velocity nuances](#velocity-nuances)
-- [Debug process](#debug-process)
-- [Scoped execution](#scoped-execution)
-- [Simulation quality](#simulation-quality)
-- [Credits and inspiration](#credits-and-inspiration)
-- [Contributing](#contributing)
-- [License](#license)
+* [Installation](#installation)
+* [Usage and command line options](#usage-and-command-line-options)
+* [Usage with Babel](#usage-with-babel)
+* [Token authorizers](#token-authorizers)
+* [Custom authorizers](#custom-authorizers)
+* [AWS API Gateway features](#aws-api-gateway-features)
+* [Velocity nuances](#velocity-nuances)
+* [Debug process](#debug-process)
+* [Scoped execution](#scoped-execution)
+* [Simulation quality](#simulation-quality)
+* [Credits and inspiration](#credits-and-inspiration)
+* [Contributing](#contributing)
+* [License](#license)
 
 ## Installation
 
@@ -52,6 +54,7 @@ First, add Serverless Offline to your project:
 Then inside your project's `serverless.yml` file add following entry to the plugins section: `serverless-offline`. If there is no plugin section you will need to add it to the file.
 
 It should look something like this:
+
 ```YAML
 plugins:
   - serverless-offline
@@ -61,7 +64,7 @@ You can check wether you have successfully installed the plugin by running the s
 
 `serverless`
 
-the console should display *Offline* as one of the plugins now available in your Serverless project.
+the console should display _Offline_ as one of the plugins now available in your Serverless project.
 
 ## Usage and command line options
 
@@ -108,11 +111,11 @@ Options passed on the command line override YAML options.
 
 By default you can send your requests to `http://localhost:3000/`. Please note that:
 
-- You'll need to restart the plugin if you modify your `serverless.yml` or any of the default velocity template files.
-- The event object passed to your λs has one extra key: `{ isOffline: true }`. Also, `process.env.IS_OFFLINE` is `true`.
-- When no Content-Type header is set on a request, API Gateway defaults to `application/json`, and so does the plugin.
-But if you send an `application/x-www-form-urlencoded` or a `multipart/form-data` body with an `application/json` (or no) Content-Type, API Gateway won't parse your data (you'll get the ugly raw as input), whereas the plugin will answer 400 (malformed JSON).
-Please consider explicitly setting your requests' Content-Type and using separate templates.
+* You'll need to restart the plugin if you modify your `serverless.yml` or any of the default velocity template files.
+* The event object passed to your λs has one extra key: `{ isOffline: true }`. Also, `process.env.IS_OFFLINE` is `true`.
+* When no Content-Type header is set on a request, API Gateway defaults to `application/json`, and so does the plugin.
+  But if you send an `application/x-www-form-urlencoded` or a `multipart/form-data` body with an `application/json` (or no) Content-Type, API Gateway won't parse your data (you'll get the ugly raw as input), whereas the plugin will answer 400 (malformed JSON).
+  Please consider explicitly setting your requests' Content-Type and using separate templates.
 
 ## Usage with Babel
 
@@ -123,6 +126,7 @@ To do so you need to install (at least) the es2015 preset in your project folder
 
 Your λ handlers can be required with `babel-register`.
 To do so, in your `serverless.yml` file, set options to be passed to babel-register like this:
+
 ```yml
 custom:
   serverless-offline:
@@ -143,6 +147,7 @@ yarn add -D babel-preset-env babel-preset-flow babel-plugin-transform-runtime ba
 ```
 
 Then, in your `.babelrc`:
+
 ```
 {
   "presets": [
@@ -178,16 +183,19 @@ Serverless-offline will emulate the behaviour of APIG and create a random token
 Only [custom authorizers](https://aws.amazon.com/blogs/compute/introducing-custom-authorizers-in-amazon-api-gateway/) are supported. Custom authorizers are executed before a Lambda function is executed and return an Error or a Policy document.
 
 The Custom authorizer is passed an `event` object as below:
+
 ```javascript
 {
   "type": "TOKEN",
   "authorizationToken": "<Incoming bearer token>",
   "methodArn": "arn:aws:execute-api:<Region id>:<Account id>:<API id>/<Stage>/<Method>/<Resource path>"
 }
 ```
+
 The `methodArn` does not include the Account id or API id.
 
 The plugin only supports retrieving Tokens from headers. You can configure the header as below:
+
 ```javascript
 "authorizer": {
   "type": "TOKEN",
@@ -230,7 +238,7 @@ Works out of the box.
 ### Lambda and Lambda Proxy Integrations
 
 [Serverless doc](https://serverless.com/framework/docs/providers/aws/events/apigateway#lambda-proxy-integration)
- ~ [AWS doc](http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-create-api-as-simple-proxy-for-lambda.html)
+~ [AWS doc](http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-create-api-as-simple-proxy-for-lambda.html)
 
 Works out of the box. See examples in the manual_test directory.
 
@@ -243,12 +251,15 @@ Works out of the box. See examples in the manual_test directory.
 [AWS doc - AWS::ApiGateway::Resource](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-resource.html)
 
 Example of enabling proxy:
+
 ```
 custom:
   serverless-offline:
     resourceRoutes: true
 ```
+
 or
+
 ```
     YourCloudFormationMethodId:
       Type: AWS::ApiGateway::Method
@@ -259,6 +270,7 @@ or
           Uri: 'https://s3-${self:custom.region}.amazonaws.com/${self:custom.yourBucketName}/{proxy}'
           ......
 ```
+
 ```
 custom:
   serverless-offline:
@@ -276,6 +288,7 @@ You can set your response's headers using ResponseParameters.
 May not work properly. Please PR. (Difficulty: hard?)
 
 Example response velocity template:
+
 ```javascript
 "responseParameters": {
   "method.response.header.X-Powered-By": "Serverless", // a string
@@ -287,6 +300,7 @@ Example response velocity template:
 ## Velocity nuances
 
 Consider this requestTemplate for a POST endpoint:
+
 ```json
 "application/json": {
   "payload": "$input.json('$')",
@@ -298,6 +312,7 @@ Consider this requestTemplate for a POST endpoint:
 Now let's make a request with this body: `{ "id": 1 }`
 
 AWS parses the event as such:
+
 ```javascript
 {
   "payload": {
@@ -309,6 +324,7 @@ AWS parses the event as such:
 ```
 
 Whereas Offline parses:
+
 ```javascript
 {
   "payload": {
@@ -327,9 +343,9 @@ You may find other differences.
 
 Serverless offline plugin will respond to the overall framework settings and output additional information to the console in debug mode. In order to do this you will have to set the `SLS_DEBUG` environmental variable. You can run the following in the command line to switch to debug mode execution.
 
->Unix:  `export SLS_DEBUG=*`
+> Unix: `export SLS_DEBUG=*`
 
->Windows: `SET SLS_DEBUG=*`
+> Windows: `SET SLS_DEBUG=*`
 
 Interactive debugging is also possible for your project if you have installed the node-inspector module and chrome browser. You can then run the following command line inside your project's root.
 
@@ -343,6 +359,16 @@ The system will start in wait status. This will also automatically start the chr
 
 Depending on the breakpoint, you may need to call the URL path for your function in seperate browser window for your serverless function to be run and made available for debugging.
 
+## Resource permissions and AWS profile
+
+Lambda functions assume an IAM role during execution: the framework creates this role and set all the permission provided in the `iamRoleStatements` section of `serverless.yml`.
+
+However, serverless offline makes use of your local AWS profile credentials to run the lambda functions and that might result in a different set of permissions. By default, the aws-sdk would load credentials for you default AWS profile specified in your configuration file.
+
+You can change this profile directly in the code or by setting proper environment variables. Setting the `AWS_PROFILE` environment variable before calling `serverless` offline to a different profile would effectively change the credentials, e.g.
+
+`AWS_PROFILE=<profile> serverless offline`
+
 ## Scoped execution
 
 Serverless offline plugin can invoke shell scripts when a simulated server has been started up for the purposes of integration testing. Downstream plugins may tie into the
@@ -353,26 +379,25 @@ Serverless offline plugin can invoke shell scripts when a simulated server has b
 ## Simulation quality
 
 This plugin simulates API Gateway for many practical purposes, good enough for development - but is not a perfect simulator.
-Specifically, Lambda currently runs on Node v4.3.2 and v6.10.0, whereas *Offline* runs on your own runtime where no memory limits are enforced.
+Specifically, Lambda currently runs on Node v4.3.2 and v6.10.0, whereas _Offline_ runs on your own runtime where no memory limits are enforced.
 
 ## Usage with serverless-offline and serverless-webpack plugin
 
- Run `serverless offline start`. In comparison with `serverless offline`, the `start` command will fire an `init` and a `end` lifecycle hook which is needed for serverless-offline and serverless-dynamodb-local to switch off ressources.
+Run `serverless offline start`. In comparison with `serverless offline`, the `start` command will fire an `init` and a `end` lifecycle hook which is needed for serverless-offline and serverless-dynamodb-local to switch off ressources.
 
- Add plugins to your `serverless.yml` file:
- ```yaml
- plugins:
-   - serverless-webpack
-   - serverless-dynamodb-local
-   - serverless-offline #serverless-offline needs to be last in the list
- ```
+Add plugins to your `serverless.yml` file:
 
+```yaml
+plugins:
+  - serverless-webpack
+  - serverless-dynamodb-local
+  - serverless-offline #serverless-offline needs to be last in the list
+```
 
 ## Credits and inspiration
 
 This plugin was initially a fork of [Nopik](https://github.com/Nopik/)'s [Serverless-serve](https://github.com/Nopik/serverless-serve).
 
-
 ## Contributing
 
 Yes, thank you!