{"id":13850597,"url":"https://github.com/monorkin/kappa","last_synced_at":"2025-07-12T22:31:13.210Z","repository":{"id":149276414,"uuid":"83057404","full_name":"monorkin/kappa","owner":"monorkin","description":"Run AWS Lambdas locally","archived":true,"fork":false,"pushed_at":"2017-03-23T14:53:07.000Z","size":245,"stargazers_count":74,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-08-05T20:32:56.153Z","etag":null,"topics":["aws","aws-lambda","docker","docker-api","rails","ruby","ruby-on-rails"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/monorkin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-02-24T15:51:06.000Z","updated_at":"2023-10-01T17:57:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"819b86d7-037f-47fe-be51-4b604ba38a47","html_url":"https://github.com/monorkin/kappa","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monorkin%2Fkappa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monorkin%2Fkappa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monorkin%2Fkappa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monorkin%2Fkappa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/monorkin","download_url":"https://codeload.github.com/monorkin/kappa/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225839565,"owners_count":17532305,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-lambda","docker","docker-api","rails","ruby","ruby-on-rails"],"created_at":"2024-08-04T20:01:19.973Z","updated_at":"2024-11-22T03:31:38.652Z","avatar_url":"https://github.com/monorkin.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# Kappa\n\nKappa is a local AWS Lambda runner. It enables you to run Lambdas as a web\nserver on your local machine. Making testing and development faster and easier.\n\n![Demonstartion video](http://i.giphy.com/3o7bu7zFFPcMP3al8Y.gif)\n\n## Usage\n\nTo run Kappa, you will need to have [Docker](https://www.docker.com/) installed\non your machine and you need to execute the following command in the root\ndirectory of your project:\n\n```Bash\ndocker run \\\n    -v /var/run/docker.sock:/var/run/docker.sock \\\n    -p \"3000:3000\" \\\n    -p \"3001:8080\" \\\n    -e \"PROJECT_ROOT=/path/to/your/project\" \\\n    -e \"HANDLER=bin/index.handler\" \\\n    stankec/kappa\n```\n\nThis will start a web server on `http://localhost:3000` that will simulate an\nAWS Lambda. It will also start another web server on `http://localhost:3001`\nwhere you can configure what type of Lambda you want to run and which event\ntemplate should it use.\n\n__By default the API Gateway Proxy template will be used.__\n\nIf you want to persist your saved template, reconsider mounting the database of\nthe container (located at `/usr/src/app/shared/db/database.sqlite3`) on the\nhost's filesystem.\n(e.g. by adding the following flag\n`-v ./tmp_db.sqlite3:/usr/src/app/shared/db/database.sqlite3`)\n\n### Basic configuration\n\nThe bare essential arguments for running the container are:\n\n```Bash\ndocker run \\\n    -v /var/run/docker.sock:/var/run/docker.sock \\\n    -e \"PROJECT_ROOT=/path/to/your/project\" \\\n    -e \"HANDLER=bin/index.handler\" \\\n    stankec/kappa\n```\n\nKappa needs access to the host's `docker.sock` to be able to spawn Lambda\ncontainers to execute various tasks. The `PROJECT_ROOT` env variable defines\nwhich project to run as the Lambda code. `HANDLER` specifies which function in\nwhich file to use as the entry point for the Lambda.\n\n### Environment variables\n\nAll environment variables from the Kappa container will be passed to the spawned\nlambda container. E.g. if the Kappa container has an ENV variable `FOO` with the\nvalue `bar`, then the spawned Lambda container will also have an ENV variable\n`FOO` with the value `bar`. This is the intended way of passing environment\nvariables to the Lambda.\n\n### Docker-Compose\n\nConstantly running the above command can get tedious. If you have\n[docker-compose](https://docs.docker.com/compose/) installed, you can use the\nfollowing `docker-compose.yml` file:\n\n```YAML\nversion: '2'\nservices:\n  web:\n    image \"stankec/kappa\"\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock\n    ports:\n      - \"3000:3000\"\n      - \"3001:8080\"\n    environment:\n      - \"PROJECT_ROOT=$(pwd)\"\n      - \"AWS_ACCESS_KEY_ID=XXXXXXXXXXXXXXXXXXX\"\n      - \"AWS_SECRET_ACCESS_KEY=YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY\"\n      - \"AWS_REGION=some-amazon-region\"\n      - \"MY_CUSTOM_ENV_VAR=ZZZZZZZZZZZZZZZZZZZZZZZZZZZZ\"\n      - \"HANDLER=bin/index.handler\"\n    tty: true\n    stdin_open: true\n```\n\nAnd then run `docker-compose up` to start Kappa.\n__Note:__ This file assumes it's in the root directory of the project you want\nto run in the Lambda.\n\n### Templates\n\nYou can see all available templates in the\n[`shared/data/templates`](/shared/data/templates) directory.\n\nThe template which is used to run the Lambda can be changed in the configurator.\n__Note:__ The saved template doesn't change the preset template and that\nit will disappear when the container is restarted.\n\nEach template __needs__ to have at least two keys: `name` and `json`. Those keys\nare self-explanatory:\n\n* `name` - Name of the template (used only for display purposes)\n* `json` - Relative path to a file containing the template's raw JSON payload\n\nAdditionally, a template __can__ have a `fields` key, which describes how the\nvalue from the incoming HTTP request should be mapped to the event JSON. It can\nhave the following keys:\n\n* `body` - mapping of the raw HTTP body string\n* `headers` - mapping of a hash with the HTTP header key-value pairs\n* `query` - mapping of a hash with the HTTP query key-value pairs\n* `path` - mapping of the raw HTTP path string\n* `method` - mapping of the raw HTTP method string\n\nE.g. if you want to map the request's path to the key `b` of the following JSON:\n\n```JSON\n{\n  \"a\": {\n    \"b\": \"path\"\n  },\n  \"c\": \"another_path\"\n}\n```\n\nthe `fields.path` field would look like this:\n\n```Ruby\n[['a', 'b']]\n```\n\nOr in YAML format:\n\n```YAML\npath:\n  -\n    - \"a\"\n    - \"b\"\n```\n\nIf a template has multiple fields that need to be mapped to the same data from\nthe HTTP request then the value of the key can be set as an array of arrays:\n\n```Ruby\n[['a', 'b'], 'c']\n```\n\nOr in YAML format:\n\n```YAML\npath:\n  - \"c\"\n  -\n    - \"a\"\n    - \"b\"\n```\n\n## Things to note\n\nEverything the Lambda outputs to `STDOUT` will be used as the result / response.\nAnd everything that is output to `STDERR` will be visible in the logs of the\nKappa container. The Lambda runner, by default, outputs a JSON object with the\nresponse to `STDOUT` when it's finished.\n\nIn JavaScript applications `console.log` is redirected to `STDERR`.\n\n## Acknowledgments\n\nThis project wouldn't have been possible without the folks at\n[FloatingPoint](https://floatingpoint.io) who sponsored it's development.\n\n[![FloatingPoint logo](/assets/resized_fp_logo.png)](https://floatingpoint.io)\n\nAnd the folks behind\n[LambdaCI's](https://github.com/lambci/lambci)\n[docker-lambda](https://github.com/lambci/docker-lambda)\nproject. It's the backbone on top of which this application has been built.\n\n## Why kappa?\n\nWell, if AWS Lambdas are the-bleeding-edge™ enabling 'serverless'\ninfrastructure then this is a step backward - back to a server-client\ninfrastructure. The Greek letter preceding lambda (λ) is kappa (κ)...\nVery clever, I know 🤣\n\n## License\n\nThis project is licensed under the [MIT](LICENSE.txt) license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonorkin%2Fkappa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmonorkin%2Fkappa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonorkin%2Fkappa/lists"}