Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dwyl/aws-lambda-deploy
☁️ 🚀 Effortlessly deploy Amazon Web Services Lambda function(s) with a single command. Less to configure. Latest AWS SDK and Node.js v20!
https://github.com/dwyl/aws-lambda-deploy
Last synced: about 1 month ago
JSON representation
☁️ 🚀 Effortlessly deploy Amazon Web Services Lambda function(s) with a single command. Less to configure. Latest AWS SDK and Node.js v20!
- Host: GitHub
- URL: https://github.com/dwyl/aws-lambda-deploy
- Owner: dwyl
- Created: 2016-02-11T14:57:50.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2024-07-30T06:12:42.000Z (about 2 months ago)
- Last Synced: 2024-07-30T09:29:13.382Z (about 2 months ago)
- Language: JavaScript
- Homepage:
- Size: 764 KB
- Stars: 74
- Watchers: 12
- Forks: 14
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
Deploy your AWS Lambda function(s) in seconds with a single command.
[](https://github.com/dwyl/aws-lambda-deploy/actions)
[](http://codecov.io/github/dwyl/aws-lambda-deploy?branch=master)
[](https://www.npmjs.com/package/dpl)
[](http://hits.dwyl.com/dwyl/aws-lambda-deploy)
[](https://github.com/dwyl/aws-lambda-deploy/issues)
## Why? 🤷
Deploying Lambda functions *manually* involves quite a few steps.
Manually clicking buttons to upload zip files is fine the first few times
but gets old pretty quickly.
There is an *easier* way!
## What? 💭
Simplify the process of deploying a AWS Lambda Function
*without having to adopt a build tool/system*.
## How? ✅
There are ***5 Steps*** to setup deployment for your Lambda Function:
### 1. install the `dpl` package from NPM 📦
```sh
npm install dpl --save-dev
```
### 2. Ensure that the *required* AWS Environment Variables are set: 🔐
In order to use `dpl` to deploy your Lambda function,
you need to have a few environment variables defined.
e.g: `AWS_REGION` and `AWS_IAM_ROLE`.
We have created a
[`.env_sample`](https://github.com/dwyl/aws-lambda-deploy/blob/master/.env_sample)
file that shows you _exactly_ which environment variables you need.
Simply copy it into your project. e.g:
```sh
cp node_modules/dpl/.env_sample .env && echo ".env\n" >> .gitignore
```
And then update the values with the _real_ ones for your project.
> **Note**: You need to have your AWS Credentials set
to use the `aws-sdk`
if you have not yet done this,
see below for instructions.
### 3. Add the *list* of `files_to_deploy` entry to your `package.json` 📝
In your `package.json` file, add the list of files & directories
you want to be included in this zip that gets uploaded to AWS.
Example:
```js
"files_to_deploy": [ "package.json", "index.js", "lib/" ]
```
> Sample: [package.json#L14-L17](https://github.com/dwyl/aws-lambda-deploy/blob/81766f9c20157039e14703e36dbbbaef4cfb4ac3/package.json#L14-L17)
### 4. Add a deployment script to the `scripts` section in `package.json` 📜
Example:
```js
"scripts": {
"deploy": "dpl"
}
```
### 5. Use the script to *Deploy*! 🚀
```sh
npm run deploy
```
### *Congratulations* your Lambda Function is Deployed! 🎉
### *Troubleshooting* 🙅
> If you see an *error* message in your console,
> read the message and resolve it by correcting your setup.
> you have either not set your AWS Credentials or not defined
> the required environment variables.
> If you get stuck or have questions,
[*ping* us!](https://github.com/dwyl/aws-lambda-deploy/issues)
## *Implementation Detail* 👷
### *Required* Environment Variables 🔐
Deploying your Lambda function requires a few Environment Variables
to be set.
#### AWS Credentials 🕸
As with all node.js code which uses the `aws-sdk`,
it expects to have your AWS credentials stored *locally*.
Your credentials are *expected* to be at: `~/.aws/credentials`
(*e.g: if your username is* ***alex***, *your AWS credentials will
be stored at* `/Users/alex/.aws/credentials`)
If you have not yet set your AWS credentials on your machine
do this *now*. Read about the [AWS credential format](http://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-file-format).
#### `AWS_IAM_ROLE`
The script needs to know which `AWS_IAM_ROLE`
you want to use to deploy/run the function.
Example:
```sh
export AWS_IAM_ROLE=arn:aws:iam::123456789:role/LambdaExecRole
```
#### `AWS_REGION` (*where your lambda function will be deployed*)
Example:
```sh
export AWS_REGION=eu-west-1
```
#### *Optionally* you can define a `TMPDIR` Environment Variable
To make the deployment script's run faster,
and avoid forcing people to add entries into their `.gitignore` file,
we store the `/dist` directory and resulting `.zip` file
in your OS's Temporary storage.
e.g:
```sh
export TMPDIR=/path/to/where/you/want/dist/
```
### Two things to add to your `package.json`
For the deploy scrip to do its job,
we need to add two lines to our `package.json`
### List of `files_to_deploy`
In your `package.json` file, add the list of files & directories
you want to be included in your distribution.
Example:
```js
"files_to_deploy": [ "package.json", "index.js", "lib/", ".env" ]
```
This tells `dpl` to copy these files and directory (with all contents)
to the `/dist` which will be zipped and sent to AWS.
Check our
[package.json#L14-L17](https://github.com/dwyl/aws-lambda-deploy/blob/81766f9c20157039e14703e36dbbbaef4cfb4ac3/package.json#L14-L17)
file if in doubt.
## Explanation of the Steps 👩🏫
### `dpl` ("*Deploy Lambda*") performs the following 5 tasks
#### 1. *Create* the `/dist` (*distribution*) directory 📁
Instead of uploading *all* the files in a project to S3/Lambda we upload only
the *required* files. e.g: `/src` or `/lib` and `./index.js`.
While we are preparing this package, these required files are *copied* to
the (*temporary*) `/dist` directory which will be *zipped* in Step 5.
> Why a *temporary* directory?
see: http://stackoverflow.com/questions/17946360/what-are-the-benefits-of-using-the-official-temp-directory-for-the-os
#### 2. *Copy* required files into `/dist` directory ☕️
This typically includes the following:
+ `lib/` - the directory containing custom code your lambda function uses.
+ `package.json` - the "manifest" file for your project,
includes the Lambda function name, any configuration and dependencies.
+ `index.js` - the "*main*" `handler` of your Lambda function.
#### 3. *Install* (*only production*) `node_modules` in `/dist` directory 📥
We only need the "*production*" dependencies to be zipped and shipped.
so instead of copying all the *devDependencies* in `node_modules`,
we simply install a fresh set using the `--production` flag.
#### 4. *Zip* the contents of the `/dist` folder to `{function_name}.zip` 📦
Once the `/dist` directory has been created with the necessary files
and the dependencies have been installed in `/dist/node_modules`
we `zip` the "*distribution*" ready for uploading to AWS.
This can take a few seconds depending on how many dependencies your
Lambda function has.
#### 5. *Upload* 🚀
Once the `zip` has been packaged we upload it to AWS using the `aws-sdk`.
Your Lambda function will be named according to the `"name"` in
the `package.json` file for your project.
> **Note**: We are using the ***latest stable version*** of **Node.js**
when deploying packages.
see: https://aws.amazon.com/blogs/compute/node-js-4-3-2-runtime-now-available-on-lambda/
If for any reason you *prefer*/*need* to use
the "*Old*" (*legacy*) version, please let us know:
https://github.com/dwyl/aws-lambda-deploy/issues/33
### Advantages of using `dpl` to *deploy* your Lambdas 💡
+ **Minial Dependencies** - Our solution to the deployment task uses only *one*
core dependency: the [`aws-sdk`](https://github.com/aws/aws-sdk-js).
+ **Small Code** - The *entire* `dpl` ("*Deploy Lambda*") module is fewer lines
than our original
[`gulpfile.js`](https://github.com/dwyl/aws-lambda-canary/blob/d18ccc099ec4ab1a7a612716563ec57364c03cc4/gulpfile.js)
and uses *only* node.js core modules
(*you know and love*) and your OS-native `zip` command.
+ A *beginner* can ***read and understand*** all the code used in `dpl`
in a few minutes; our code has *both* JavaDoc and *in-line comments* and we are
[*here*](https://github.com/dwyl/aws-lambda-deploy/issues)
to help if you have *any questions*!
+ **No assumptions** about your code style.
e.g if you need any custom processing
simply add a task in your `scripts` section of your `package.json`
and run that task before deploying.
+ **No _Global_ packages** required or implied, just *one `dev` Dependency*.
### Optional configuration
Want to specify the `MemorySize` or `Timeout` settings for your Lambda function?
+ `"lambda_memory"` - maximum memory allocation for your lambda function.
+ `"lambda_timeout"` - maximum execution time.
In your `package.json` add:
```js
"lambda_memory":"512",
"lambda_timeout": "30",
```
### *Environment Variables*?
Unlike other AWS Lambda deployment methods,
`dpl` lets you use environment
variables in your Lambda Functions!
Simply add `.env` to your list of `"files_to_deploy"` in your `package.json`
Example:
```js
"files_to_deploy": [ "package.json", "index.js", "lib/", ".env" ]
```
And an `.env` file will included in your `.zip` file that gets uploaded to AWS.
This means you can use an Environment Variable loader
e.g [`env2`](https://www.npmjs.com/package/env2)
in your Lambda function:
```js
require('env2')('.env');
exports.handler = (event, context) => {
if (event.hello === 'world') {
return context.fail(JSON.stringify({
statusCode: 500,
message: 'sorry'
}));
} else {
return context.succeed({
statusCode: 200,
message: process.env.HELLO // or how ever you use environment variables!
});
}
};
```
## Suggested Reading 👀
+ Using NPM as a build tool:
http://blog.keithcirkel.co.uk/how-to-use-npm-as-a-build-tool/
(*you don't need gulp/grunt/etc...*)