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.
To run Kappa, you will need to have Docker installed on your machine and you need to execute the following command in the root directory of your project:
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
)
The bare essential arguments for running the container are:
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.
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.
Constantly running the above command can get tedious. If you have
docker-compose installed, you can use the
following docker-compose.yml
file:
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.
You can see all available templates in the
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 stringheaders
- mapping of a hash with the HTTP header key-value pairsquery
- mapping of a hash with the HTTP query key-value pairspath
- mapping of the raw HTTP path stringmethod
- 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:
{
"a": {
"b": "path"
},
"c": "another_path"
}
the fields.path
field would look like this:
[['a', 'b']]
Or in YAML format:
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:
[['a', 'b'], 'c']
Or in YAML format:
path:
- "c"
-
- "a"
- "b"
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
.
This project wouldn't have been possible without the folks at FloatingPoint who sponsored it's development.
And the folks behind LambdaCI's docker-lambda project. It's the backbone on top of which this application has been built.
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 🤣
This project is licensed under the MIT license.