{"id":16189004,"url":"https://github.com/fogfish/serverless","last_synced_at":"2025-03-19T03:30:44.566Z","repository":{"id":57546963,"uuid":"132781301","full_name":"fogfish/serverless","owner":"fogfish","description":"Serverless Erlang runtime for AWS Lambda Service","archived":false,"fork":false,"pushed_at":"2019-11-06T18:37:13.000Z","size":172,"stargazers_count":29,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-15T12:02:35.424Z","etag":null,"topics":["aws-cdk","aws-lambda","aws-lambda-erlang","aws-lambda-layer","erlang","lambda","serverless"],"latest_commit_sha":null,"homepage":"","language":"Erlang","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/fogfish.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-09T16:01:36.000Z","updated_at":"2023-10-13T17:30:56.000Z","dependencies_parsed_at":"2022-09-26T18:40:42.060Z","dependency_job_id":null,"html_url":"https://github.com/fogfish/serverless","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fogfish%2Fserverless","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fogfish%2Fserverless/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fogfish%2Fserverless/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fogfish%2Fserverless/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fogfish","download_url":"https://codeload.github.com/fogfish/serverless/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243965774,"owners_count":20375917,"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-cdk","aws-lambda","aws-lambda-erlang","aws-lambda-layer","erlang","lambda","serverless"],"created_at":"2024-10-10T07:33:19.461Z","updated_at":"2025-03-19T03:30:44.083Z","avatar_url":"https://github.com/fogfish.png","language":"Erlang","funding_links":[],"categories":[],"sub_categories":[],"readme":"# serverless\n\nServerless Erlang runtime for AWS Lambda Service, widen horizon of Erlang applications.\n\n[![Build Status](https://secure.travis-ci.org/fogfish/serverless.svg?branch=master)](http://travis-ci.org/fogfish/serverless) \n[![Coverage Status](https://coveralls.io/repos/github/fogfish/serverless/badge.svg?branch=master)](https://coveralls.io/github/fogfish/serverless?branch=master)\n[![Hex.pm](https://img.shields.io/hexpm/v/serverless.svg)](https://hex.pm/packages/serverless)\n\n\n## Inspiration\n\nRun code without provisioning or managing servers is a modern way to deliver applications. This library enables Erlang runtime at AWS Lambda service using [AWS Lambda Runtime Interface](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-api.html). The Erlang runtime is deployed as [AWS Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html) to your AWS account.\n\nThe library uses [escript](http://erlang.org/doc/man/escript.html) executable to package, debug and deploy lambda functions.\n\n\n## Key features\n\n* Implements Erlang runtime for AWS Lambda service.\n* Deploys Erlang\\OTP as AWS Lambda Layer.\n* Defines a lambda's life-cycle workflow using AWS CDK.\n* Provides command line tools to orchestrate local development and production deployments.\n\n\n## Getting started\n\nThe latest version of the library is available at its `master` branch. All development, including new features and bug fixes, take place on the `master` branch using forking and pull requests as described in contribution guidelines.\n\nThe stable library release is available via hex packages, add the library as dependency to rebar.config\n\n```erlang\n{deps, [\n  serverless\n]}.\n```\n\nLatest development version is available at GitHub, add the library as dependency to rebar.config\n\n```erlang\n{deps, [\n   {serverless, \".*\",\n      {git, \"https://github.com/fogfish/serverless\", {branch, master}}\n   }\n]}.\n```\n\nThe easiest way to start with Erlang serverless function development is a template provided by [serverless.mk](serverless.mk). Please look on [hello world](examples/helloworld) example as a play ground to get things up and running.\n\n\n### Workflow\n\nThe library defines a life-cycle workflow to distribute Erlang application from sources to the cloud - [AWS Lambda service](https://aws.amazon.com/lambda/). The workflow builds a distribution package of Erlang application using rebar3 with help of Makefile orchestration. The file [serverless.mk](serverless.mk) implements the workflow:\n\n1. [Configure AWS account](#configure-aws-account). \n2. [Create a new function](#create-a-new-function).\n3. [Build function](#build-function)\n4. [Run function locally](#run-function-locally)\n5. [Package function](#package-function)\n6. [Deploy function](#deploy-function)\n7. [Clean up](#clean-up)\n\n\n### Configure AWS account\n\nUsage of [AWS Lambda Layers](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html) simplifies an experience of lambda development and deployment. A custom Erlang runtime is provisioned with layers feature. The library uses docker image `fogfish/erlang-serverless` to distribute a runtime compatible with AWS Lambda service, the image is managed by [erlang-in-docker](https://github.com/fogfish/erlang-in-docker).\n\nYou have to deploy a layer to you account before you'll be able to run any function. The following command builds a zip archive with Erlang runtime and deploys it your AWS account. Please notice, this operation has to be executed only once per AWS Account.\n\n```\ncd examples/helloworld\n\nmake layer\n```\n\n\n### Create a new function\n\nThe easiest way to start with Erlang serverless function development is a template provided by [serverless.mk](serverless.mk). Create a new folder for your function and download the workflow orchestration file. \n\n```bash\nmkdir myfun \u0026\u0026 cd myfun\n\ncurl -O -L https://raw.githubusercontent.com/fogfish/serverless/master/serverless.mk\n```\n\nthen, create a Makefile. Please note, `EVENT` a default mock event used by local execution.\n\n```bash\ncat \u003e Makefile \u003c\u003cEOF\nAPP       = name_of_my_function\nEVENT    ?= test/event.json\n\ninclude serverless.mk\nEOF\n```\n\nUse build-in template to generate empty function\n\n```bash\nmake function\n```\n\nThe command downloads a [docker images](https://github.com/fogfish/erlang-in-docker) with serverless runtime, creates a source code of identity function, empty test suites, rebar config files and initializes deployment configurations. As the result, the following folder structure is created\n\n```\n+\n+- cloud                           // cloud deployment configurations\n|  +- aws.ts                       // aws cdk deployment template\n| ...\n+- src                             // source code of lambda function\n|  +- name-of-my-function.app.src\n|  +- name-of-my-function.erl\n+- test                            // tests of lambda function\n|  +- event.json                   // specification of default event mock\n|  |\n| ...\n+- rebar.config\n```\n\nYou project is ready for development.\n\n\n### Build function\n\nUse default Makefile target to compile and test the application. Serverless library promotes a [Erlang Common Tests](http://erlang.org/doc/apps/common_test/introduction.html) for automated testing.\n\n```bash\nmake\n```\n\nYou can also invoke compile and test targets sequentially.\n\n```bash\nmake compile\nmake test\n```\n\nThe library provides a Lambda Runtime API mock `serverless:mock`, use to test your code.\n\n```erlang\n#{\u003c\u003c\"helloworld\"\u003e\u003e =\u003e #{}} = serverless:mock(\n   helloworld,               %% Function entry point\n   #{}                       %% Mock input, mock function returns Lambda output\n).\n```\n\n\n### Run function locally\n\nRuns your Amazon Lambda function locally. It passes content of `test/event.json` as Amazon Lambda event object.\n\n```bash\nmake run\n```\n\nUse `EVENT` variable to pass other than default event\n\n```bash\nmake run EVENT=test/kinesis.json\n```\n\nOften, AWS Lambda Event contains in-line JSON as string (e.g. Gateway API, Kinesis, etc). Maintainability of such content for mock purposes is tedious. You can use template feature to maintain event metadata and payload in different files.\n\n```json\n// test/event.json\n{\n  \"path\": \"/test/hello\",\n  \"headers\": { ... },\n  \"body\": $json\n}\n\n// test/payload.json\n{\n  \"foo\": \"bar\",\n  \"boo\": \"baa\"\n}\n```\n\nThen use `JSON` variable to bind content of `$json` variable to a file\n\n```bash\nmake run JSON=test/payload.json\n```\n\n### Package function\n\nUse **dist** target to assemble an escript executable containing the project's and its dependencies' BEAM files. \n\n```bash\nmake dist\n```\n\nAs the result, `_build/default/bin/name-of-my-function` executable. \n\n\n### Deploy function\n\nThe workflow implements a target **dist-up** to orchestrate deployment with help of [AWS CDK](https://aws.amazon.com/cdk/).\n\nTo deploy a function, you need a stack configuration. The serverless library manages environment configurations at `cloud` folder. The stack contains reference to an execution role, lambda layer and other. A minimal configuration is supplied as part of function template. Please refers to official AWS CDK documentation if you need to make advanced config.\n\nAfter the stack configuration is completed, deploy it\n\n```bash\nmake dist-up\n```\n\n**Congratulations, your function is production ready!**\n\n\n### Clean up\n\nA few targets are supported:\n\n* **dist-rm** remove lambda deployment(s) at specified environment.\n* **clean** build artifacts.\n* **distclean** clean up everything except source code.\n\n\n## How To Contribute\n\nThe library is [MIT](https://en.wikipedia.org/wiki/MIT_License) licensed and accepts contributions via GitHub pull requests:\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Added some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\nThe development requires [Erlang/OTP](http://www.erlang.org/downloads) version 20.0 or later and essential build tools.\n\n### commit message\n\nThe commit message helps us to write a good release note, speed-up review process. The message should address two question what changed and why. The project follows the template defined by chapter [Contributing to a Project](http://git-scm.com/book/ch5-2.html) of Git book.\n\n\u003e\n\u003e Short (50 chars or less) summary of changes\n\u003e\n\u003e More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together.\n\u003e \n\u003e Further paragraphs come after blank lines.\n\u003e \n\u003e Bullet points are okay, too\n\u003e \n\u003e Typically a hyphen or asterisk is used for the bullet, preceded by a single space, with blank lines in between, but conventions vary here\n\u003e\n\u003e\n\n### bugs\n\nIf you experience any issues with the library, please let us know via [GitHub issues](https://github.com/fogfish/serverless/issue). We appreciate detailed and accurate reports that help us to identity and replicate the issue. \n\n* **Specify** the configuration of your environment. Include which operating system you use and the versions of runtime environments. \n\n* **Attach** logs, screenshots and exceptions, in possible.\n\n* **Reveal** the steps you took to reproduce the problem, include code snippet or links to your project.\n\n\n## License\n\n[![See LICENSE](https://img.shields.io/github/license/fogfish/serverless.svg?style=for-the-badge)](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffogfish%2Fserverless","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffogfish%2Fserverless","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffogfish%2Fserverless/lists"}