Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/monorkin/kappa

Run AWS Lambdas locally
https://github.com/monorkin/kappa

aws aws-lambda docker docker-api rails ruby ruby-on-rails

Last synced: 3 months ago
JSON representation

Run AWS Lambdas locally

Host: GitHub
URL: https://github.com/monorkin/kappa
Owner: monorkin
License: mit
Archived: true
Created: 2017-02-24T15:51:06.000Z (over 7 years ago)
Default Branch: master
Last Pushed: 2017-03-23T14:53:07.000Z (over 7 years ago)
Last Synced: 2024-07-21T00:37:12.992Z (4 months ago)
Topics: aws, aws-lambda, docker, docker-api, rails, ruby, ruby-on-rails
Language: Ruby
Size: 239 KB
Stars: 74
Watchers: 2
Forks: 3
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE.txt

Awesome Lists containing this project

README

# Kappa

Kappa is a local AWS Lambda runner. It enables you to run Lambdas as a web
server on your local machine. Making testing and development faster and easier.

![Demonstartion video](http://i.giphy.com/3o7bu7zFFPcMP3al8Y.gif)

## Usage

To run Kappa, you will need to have [Docker](https://www.docker.com/) installed
on your machine and you need to execute the following command in the root
directory of your project:

```Bash
docker run \
-v /var/run/docker.sock:/var/run/docker.sock \
-p "3000:3000" \
-p "3001:8080" \
-e "PROJECT_ROOT=/path/to/your/project" \
-e "HANDLER=bin/index.handler" \
stankec/kappa
```

This will start a web server on `http://localhost:3000` that will simulate an
AWS Lambda. It will also start another web server on `http://localhost:3001`
where you can configure what type of Lambda you want to run and which event
template should it use.

__By default the API Gateway Proxy template will be used.__

If you want to persist your saved template, reconsider mounting the database of
the container (located at `/usr/src/app/shared/db/database.sqlite3`) on the
host's filesystem.
(e.g. by adding the following flag
`-v ./tmp_db.sqlite3:/usr/src/app/shared/db/database.sqlite3`)

### Basic configuration

The bare essential arguments for running the container are:

```Bash
docker run \
-v /var/run/docker.sock:/var/run/docker.sock \
-e "PROJECT_ROOT=/path/to/your/project" \
-e "HANDLER=bin/index.handler" \
stankec/kappa
```

Kappa needs access to the host's `docker.sock` to be able to spawn Lambda
containers to execute various tasks. The `PROJECT_ROOT` env variable defines
which project to run as the Lambda code. `HANDLER` specifies which function in
which file to use as the entry point for the Lambda.

### Environment variables

All environment variables from the Kappa container will be passed to the spawned
lambda container. E.g. if the Kappa container has an ENV variable `FOO` with the
value `bar`, then the spawned Lambda container will also have an ENV variable
`FOO` with the value `bar`. This is the intended way of passing environment
variables to the Lambda.

### Docker-Compose

Constantly running the above command can get tedious. If you have
[docker-compose](https://docs.docker.com/compose/) installed, you can use the
following `docker-compose.yml` file:

```YAML
version: '2'
services:
web:
image "stankec/kappa"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
ports:
- "3000:3000"
- "3001:8080"
environment:
- "PROJECT_ROOT=$(pwd)"
- "AWS_ACCESS_KEY_ID=XXXXXXXXXXXXXXXXXXX"
- "AWS_SECRET_ACCESS_KEY=YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"
- "AWS_REGION=some-amazon-region"
- "MY_CUSTOM_ENV_VAR=ZZZZZZZZZZZZZZZZZZZZZZZZZZZZ"
- "HANDLER=bin/index.handler"
tty: true
stdin_open: true
```

And then run `docker-compose up` to start Kappa.
__Note:__ This file assumes it's in the root directory of the project you want
to run in the Lambda.

### Templates

You can see all available templates in the
[`shared/data/templates`](/shared/data/templates) directory.

The template which is used to run the Lambda can be changed in the configurator.
__Note:__ The saved template doesn't change the preset template and that
it will disappear when the container is restarted.

Each template __needs__ to have at least two keys: `name` and `json`. Those keys
are self-explanatory:

* `name` - Name of the template (used only for display purposes)
* `json` - Relative path to a file containing the template's raw JSON payload

Additionally, a template __can__ have a `fields` key, which describes how the
value from the incoming HTTP request should be mapped to the event JSON. It can
have the following keys:

* `body` - mapping of the raw HTTP body string
* `headers` - mapping of a hash with the HTTP header key-value pairs
* `query` - mapping of a hash with the HTTP query key-value pairs
* `path` - mapping of the raw HTTP path string
* `method` - mapping of the raw HTTP method string

E.g. if you want to map the request's path to the key `b` of the following JSON:

```JSON
{
"a": {
"b": "path"
},
"c": "another_path"
}
```

the `fields.path` field would look like this:

```Ruby
[['a', 'b']]
```

Or in YAML format:

```YAML
path:
-
- "a"
- "b"
```

If a template has multiple fields that need to be mapped to the same data from
the HTTP request then the value of the key can be set as an array of arrays:

```Ruby
[['a', 'b'], 'c']
```

Or in YAML format:

```YAML
path:
- "c"
-
- "a"
- "b"
```

## Things to note

Everything the Lambda outputs to `STDOUT` will be used as the result / response.
And everything that is output to `STDERR` will be visible in the logs of the
Kappa container. The Lambda runner, by default, outputs a JSON object with the
response to `STDOUT` when it's finished.

In JavaScript applications `console.log` is redirected to `STDERR`.

## Acknowledgments

This project wouldn't have been possible without the folks at
[FloatingPoint](https://floatingpoint.io) who sponsored it's development.

[![FloatingPoint logo](/assets/resized_fp_logo.png)](https://floatingpoint.io)

And the folks behind
[LambdaCI's](https://github.com/lambci/lambci)
[docker-lambda](https://github.com/lambci/docker-lambda)
project. It's the backbone on top of which this application has been built.

## Why kappa?

Well, if AWS Lambdas are the-bleeding-edge™ enabling 'serverless'
infrastructure then this is a step backward - back to a server-client
infrastructure. The Greek letter preceding lambda (λ) is kappa (κ)...
Very clever, I know 🤣

## License

This project is licensed under the [MIT](LICENSE.txt) license.