1 | # node-lambda
|
2 |
|
3 | ![node-lambda](../master/node-lambda.png?raw=true)
|
4 |
|
5 | Command line tool to locally run and deploy your node.js application to [Amazon Lambda](http://aws.amazon.com/lambda/).
|
6 |
|
7 | [![BuildStatus](https://travis-ci.org/motdotla/node-lambda.svg?branch=master)](https://travis-ci.org/motdotla/node-lambda)
|
8 | [![NPM version](https://badge.fury.io/js/node-lambda.svg)](http://badge.fury.io/js/node-lambda)
|
9 |
|
10 | ```
|
11 | $ node-lambda run
|
12 | ```
|
13 |
|
14 | ## Installation
|
15 |
|
16 | ```
|
17 | $ npm install -g node-lambda
|
18 | ```
|
19 |
|
20 | ## Example App
|
21 |
|
22 | The [node-lambda-template](https://github.com/RebelMail/node-lambda-template) example app makes it easy to get up and running.
|
23 |
|
24 | ## Usage
|
25 |
|
26 | There are 4 available commands.
|
27 |
|
28 | ```
|
29 | $ node-lambda setup
|
30 | $ node-lambda run
|
31 | $ node-lambda package
|
32 | $ node-lambda deploy
|
33 | ```
|
34 |
|
35 | ### Commands
|
36 |
|
37 | #### setup
|
38 |
|
39 | Initializes the `event.json`, `context.json`, `.env`, `deploy.env` files, and `event_sources.json` files. `event.json` is where you mock your event. `context.json` is where you can add additional mock data to the context passed to your lambda function. `.env` is where you place your deployment configuration. `deploy.env` has the same format as `.env`, but is used for holding any environment/config variables that you need to be deployed with your code to Lambda but you don't want in version control (e.g. DB connection info). `event_sources.json` is used to set the event source of the Lambda function (Not all event sources available in Lambda are supported).
|
40 |
|
41 | ```
|
42 | $ node-lambda setup --help
|
43 |
|
44 | Usage: setup [options]
|
45 |
|
46 | Options:
|
47 |
|
48 | -h, --help output usage information
|
49 | ```
|
50 |
|
51 | After running setup, it's a good idea to gitignore the generated `event.json` and `.env` files, as well as `.lambda`.
|
52 |
|
53 | ```
|
54 | $ echo -e ".env\ndeploy.env\nevent.json\n.lambda" >> .gitignore
|
55 | ```
|
56 |
|
57 | ##### Deploy env variables
|
58 |
|
59 | ```
|
60 | AWS_ENVIRONMENT // (default: '')
|
61 | CONFIG_FILE // (default: '')
|
62 | EVENT_SOURCE_FILE // (default: '')
|
63 | EXCLUDE_GLOBS // (default: '')
|
64 | AWS_ACCESS_KEY_ID // (default: not set!)
|
65 | AWS_SECRET_ACCESS_KEY // (default: not set!)
|
66 | AWS_PROFILE = // (default: '')
|
67 | AWS_SESSION_TOKEN = // (default: '')
|
68 | AWS_REGION = // (default: 'us-east-1,us-west-2,eu-west-1')
|
69 | AWS_FUNCTION_NAME // (default: package.json.name or 'UnnamedFunction')
|
70 | AWS_HANDLER // (default: 'index.handler')
|
71 | AWS_ROLE_ARN || AWS_ROLE // (default: 'missing')
|
72 | AWS_MEMORY_SIZE // (default: 128)
|
73 | AWS_TIMEOUT // (default: 60)
|
74 | AWS_RUN_TIMEOUT // (default: 3)
|
75 | AWS_DESCRIPTION // (default: package.json.description or '')
|
76 | AWS_RUNTIME // (default: 'nodejs6.10')
|
77 | AWS_PUBLISH // (default: false)
|
78 | AWS_FUNCTION_VERSION // (default: '')
|
79 | AWS_VPC_SUBNETS // (default: '')
|
80 | AWS_VPC_SECURITY_GROUPS // (default: '')
|
81 | AWS_TRACING_CONFIG // (default: '')
|
82 | EVENT_FILE // (default: 'event.json')
|
83 | PACKAGE_DIRECTORY // (default: not set)
|
84 | CONTEXT_FILE // (default: 'context.json')
|
85 | PREBUILT_DIRECTORY // (default: '')
|
86 | SRC_DIRECTORY // (default: '')
|
87 | DEPLOY_TIMEOUT // (default: '120000')
|
88 | DOCKER_IMAGE // (default: '')
|
89 | DEPLOY_ZIPFILE // (default: '')
|
90 | AWS_DLQ_TARGET_ARN // (default: not set)
|
91 | ```
|
92 |
|
93 | #### run
|
94 |
|
95 | Runs your Amazon Lambda index.js file locally. Passes `event.json` data to the Amazon Lambda event object.
|
96 |
|
97 | ```
|
98 | $ node-lambda run --help
|
99 |
|
100 | Usage: run [options]
|
101 |
|
102 | Options:
|
103 |
|
104 | -h, --help Output usage information
|
105 | -H, --handler [index.handler] Lambda Handler {index.handler}
|
106 | -j, --eventFile [event.json] Event JSON File
|
107 | -f, --configFile [] Path to file holding secret environment variables (e.g. "deploy.env")
|
108 | -u, --runtime [nodejs6.10] Lambda Runtime {nodejs6.10, nodejs4.3}
|
109 | -t, --timeout [3] Lambda Timeout in seconds (max of 300)
|
110 | -x, --contextFile [context.json] Context JSON file
|
111 | ```
|
112 |
|
113 | #### package
|
114 |
|
115 | Bundles your application into a local zip file.
|
116 |
|
117 | ```
|
118 | $ node-lambda package --help
|
119 |
|
120 | Usage: package [options]
|
121 |
|
122 | Options:
|
123 |
|
124 | -h, --help output usage information
|
125 | -A, --packageDirectory [build] Local Package Directory
|
126 | -I, --dockerImage [] Docker image for npm install
|
127 | -n, --functionName [node-lambda] Lambda FunctionName
|
128 | -H, --handler [index.handler] Lambda Handler {index.handler}
|
129 | -e, --environment [staging] Choose environment {development, staging, production}
|
130 | -f, --configFile [] Path to file holding secret environment variables (e.g. "deploy.env")
|
131 | -x, --excludeGlobs [] Add a space separated list of file(type)s to ignore (e.g. "*.json .env")
|
132 | -D, --prebuiltDirectory [] Prebuilt directory
|
133 |
|
134 | ```
|
135 |
|
136 | #### deploy
|
137 |
|
138 | Bundles and deploys your application up to Amazon Lambda.
|
139 |
|
140 | ```
|
141 | $ node-lambda deploy --help
|
142 |
|
143 | Usage: deploy [options]
|
144 |
|
145 | Options:
|
146 |
|
147 | -h, --help output usage information
|
148 | -e, --environment [staging] Choose environment {development, staging, production}
|
149 | -a, --accessKey [your_key] AWS Access Key
|
150 | -s, --secretKey [your_secret] AWS Secret Key
|
151 | -P, --profile [your_profile] AWS Profile
|
152 | -k, --sessionToken [your_token] AWS Session Token
|
153 | -r, --region [us-east-1] AWS Region(s)
|
154 | -n, --functionName [node-lambda] Lambda FunctionName
|
155 | -H, --handler [index.handler] Lambda Handler {index.handler}
|
156 | -o, --role [your_role] Amazon Role ARN
|
157 | -m, --memorySize [128] Lambda Memory Size
|
158 | -t, --timeout [3] Lambda Timeout
|
159 | -d, --description [missing] Lambda Description
|
160 | -u, --runtime [nodejs6.10] Lambda Runtime {nodejs6.10, nodejs4.3}
|
161 | -p, --publish [false] This boolean parameter can be used to request AWS Lambda to create the Lambda function and publish a version as an atomic operation
|
162 | -L, --lambdaVersion [custom-version] Lambda Version
|
163 | -f, --configFile [] Path to file holding secret environment variables (e.g. "deploy.env")
|
164 | -b, --vpcSubnets [] VPC Subnet ID(s, comma separated list) for your Lambda Function, when using this, the below param is also required
|
165 | -g, --vpcSecurityGroups [] VPC Security Group ID(s, comma separated list) for your Lambda Function, when using this, the above param is also required
|
166 | -Q, --deadLetterConfigTargetArn [] Lambda DLQ resource
|
167 | -T, --tracingConfig [] Lambda tracing settings
|
168 | -A, --packageDirectory [] Local package directory
|
169 | -I, --dockerImage [] Docker image for npm install
|
170 | -S, --eventSourceFile [event_sources.json] Path to file holding event source mapping variables (e.g. "event_sources.json")
|
171 | -x, --excludeGlobs [] Add a space separated list of file(type)s to ignore (e.g. "*.json .env")
|
172 | -D, --prebuiltDirectory [] Prebuilt directory
|
173 | -z, --deployZipfile [] Deploy zipfile
|
174 | -T, --deployTimeout [120000] Deploy Timeout
|
175 | -G, --sourceDirectory [.] Path to lambda source Directory (e.g. "./some-lambda")
|
176 | ```
|
177 |
|
178 | ## Custom Environment Variables
|
179 |
|
180 | AWS Lambda will let you set environment variables for your function. Use the sample `deploy.env` file in combination with the `--configFile` flag to set values which will be added to the lambda configuration upon deploy. Environment variables will also be set when running locally using the same flag
|
181 |
|
182 | ## Node.js Runtime Configuration
|
183 |
|
184 | AWS Lambda now supports Node.js 6.10 and Node.js 4.3. Please also check the [Programming Model (Node.js)](http://docs.aws.amazon.com/lambda/latest/dg/programming-model.html) page.
|
185 |
|
186 | ## Post install script
|
187 | When running `node-lambda deploy` if you need to do some action after `npm install --production` and before deploying to AWS Lambda (e.g. replace some modules with precompiled ones or download some libraries, replace some config file depending on environment) you can create `post_install.sh` script. If the file exists the script will be executed (and output shown after execution) if not it is skipped. Environment string is passed to script as first parameter so you can use it if needed. Make sure that the script is executable.
|
188 |
|
189 | Example `post_install.sh`:
|
190 | ```
|
191 | printf "\n\n###### Post install script ###### \n"
|
192 | ENV="production";
|
193 | if [ ! -z $1 ]
|
194 | then
|
195 | ENV=$1;
|
196 | fi
|
197 | cp -v "config_$ENV.js" "config.js" \
|
198 | && printf "###### DONE! ###### \n\n"
|
199 | ```
|
200 |
|
201 | ## Post invoke script (example)
|
202 | If you wish to invoke your deployed AWS Lambda function, you can add the following as a `script` to your `package.json`:
|
203 |
|
204 | ```
|
205 | "invoke:remote": "aws lambda invoke --function-name myLambdaFnName --payload fileb://fixtures/hi.json invoked.json --log-type Tail | jq -r '.LogResult' | base64 --decode && rm invoked.json"
|
206 | ```
|
207 |
|
208 | ## Prebuilt packages
|
209 | The `--prebuiltDirectory` flag is useful for working with Webpack for example. It skips `npm install --production` and `post_install.sh` and simply packages the specified directory.
|
210 |
|
211 | ## Handling `npm link` and Dependencies With Local Paths
|
212 | Perhaps the easiest way to handle these cases is to bundle the code using Webpack and use the `--prebuiltDirectory` flag to package the output for deployment.
|
213 |
|
214 | ## ScheduleEvents
|
215 | #### Optional Parameter
|
216 | When using the eventSourceFile flag (-S or --eventSourceFile) to set a ScheduleEvent trigger, you can pass an optional _ScheduleDescription_ key into the ScheduleEvent object with a custom description for the CloudWatch event rule you are defining. By default, node-lambda generates a _ScheduleDescription_ for you based on the ScheduleName and ScheduleExpression of the rule.
|
217 |
|
218 | #### Note on ScheduleState for ScheduleEvents
|
219 | When setting ScheduleState to `ENABLED` or `DISABLED` for ScheduleEvents, it is useful to note that this sets the state of the CloudWatch Event rule but _DOES NOT_ set the state of the trigger for the Lambda function you are deploying; ScheduleEvent triggers are enabled by default in the Lambda console when added using the eventSourceFile flag.
|
220 |
|
221 | #### Known Issue
|
222 | ###### Duplicate ScheduleEvent Triggers
|
223 | If you are adding a trigger via the `eventSourceFile` for the first time, remove preexisting triggers from the Lambda console before deploying. Deploying a Lambda with the `--eventSourceFile` flag will *NOT* overwrite the same triggers created from the AWS console and may result in a duplicate triggers for the same rule.
|
224 |
|
225 | ## Other AWS Lambda Tools Projects
|
226 |
|
227 | + [lambdaws](https://github.com/mentum/lambdaws)
|
228 | + [lambdaws-instant-api](https://github.com/mentum/lambdaws-instant-api)
|
229 |
|
230 | ## Contributing
|
231 |
|
232 | 1. Fork it
|
233 | 2. Create your feature branch (`git checkout -b my-new-feature`)
|
234 | 3. Commit your changes (`git commit -am 'Added some feature'`)
|
235 | 4. Push to the branch (`git push origin my-new-feature`)
|
236 | 5. Create new Pull Request
|
237 |
|
238 | ### Coding style
|
239 | This project uses [JavaScript Standard Style](https://standardjs.com/).
|
240 |
|
241 | [![JavaScript Style Guide](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://github.com/feross/standard)
|
242 |
|
243 | ## Running tests
|
244 |
|
245 | ```
|
246 | $ npm install
|
247 | $ npm test
|
248 | ```
|