The goal of this project is to provide minimal code to convert API Gateway event
and context
objects into Rack events for your Rails application in a Lambda handler. Most everything else is documentation.
def handler(event:, context:)
Lamby.handler $app, event, context
end
Add the Lamby gem to your Rails project's Gemfile
. Recommend only requiring Lamby in your app.rb
so your local development or test logs still work.
gem 'lamby', require: false
Create an app.rb
file that will be the source for the Lambda's handler. Example:
require_relative 'config/boot'
require 'lamby'
require_relative 'config/application'
require_relative 'config/environment'
$app = Rack::Builder.new { run Rails.application }.to_app
def handler(event:, context:)
Lamby.handler $app, event, context
end
Create an AWS SAM template.yaml
file that expresses your function's resources and how it receives events from API Gateway. Please use this full doc/template.yaml file hosted here as a starting point. The basic template accomplishes the following.
- Defines a
RailsEnv
input parameter.- Applies this to the
RAILS_ENV
environment variable.
- Applies this to the
- Creates a API Gateway resource named
RailsApi
.- Ensures that the stage name is set to the Rails env.
- Using inline Swagger, define a root
/
via GET and greedy proxy/{resource+}
via ANY. - Allow any binary media type to be a valid response.
- Creates a Lambda function resource named
RailsFunction
.- Sets the handler to
app.handler
. File above. - Defines events from API above for both root and greedy proxy.
- Sets the handler to
- Simple
Outputs
that echos the resources you created.
Ensure both /.aws-sam
and /vendor/bundle
are added to .gitignore
. AWS SAM uses the .aws-sam
directory to build your project. No file there should be committed to source control.
$ echo '/.aws-sam' >> .gitignore
$ echo '/vendor/bundle' >> .gitignore
To run your Lambda locally or deploy it, please read the following docs.
In order to provide minimal code and ultimate flexibility for any type of Rails application on Lambda, optional or advanced features require that you write additional CloudFormation code or perform AWS Console actions to get the desired results.
To that end, we are using our GitHub issues along with the [docs]
label as a project-focused Stack Overflow where we encourage you to participate in and ask questions. Here are a few high level docs now that may interests most users. Also, browse all docs or open a new [question]
issue and we would be glad to help!
- Environments & Configuration
- Asset Hosts & Precompiling
- Custom Domain Name, Edge/Regional, & CloudFront
- API Gateway Permissions & CloudWatch Logs
- How Does Lamby Work?
- Performance & Real World Usage
- Database Connections
- Basic Ruby with Lambda & AWS SAM
- Docker Perf on Mac & Root Proxy SAM Bugs
AWS SAM is shorthand for the Serverless Application Model and it is a superset of CloudFormation - a language that describes and provisions your infrastructure using code. As your application grows and requires additional AWS resources, learning how to express this in your template.yaml
is critical. We recommend the following links when needing to learn both SAM and CloudFormation.
After checking out the repo, run ./bin/setup
to install dependencies. Then, run ./bin/test
to run the tests. NOTE: There are no tests now but adding them is on our TODO list.
Bug reports and pull requests are welcome on GitHub at https://github.com/customink/lamby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
Everyone interacting in the Lamby projectβs codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.