LambdaRubyBundler

LambdaRubyBundler is a command-line tool for packaging Ruby applications for AWS Lambda.

Most notably, it properly compiles dependencies with C extensions, using a custom Docker image based on lambci/lambda:build-ruby2.5.

Installation

Add this line to your application's Gemfile for programmatic usage:

gem 'lambda_ruby_bundler'

And then execute:

$ bundle

Or install it yourself as:

$ gem install lambda_ruby_bundler

Usage

Note that the library requires running Docker on your system!

Let's assume the following directory structure:

/tmp/my_serverless_app
├── Gemfile
├── Gemfile.lock
├── backend/
│   └── handler.rb
└── node_modules/...

Command line usage

Run:

lambda_ruby_bundler \
  --root-path /tmp/my_serverless_app \
  --app-path backend \
  --out /tmp/build.zip

It will produce two ZIP files, one with the contents of the application directory:

# build.zip
├ handler.rb

And one with bundled dependencies:

# build-dependencies.zip
ruby/gems/2.5.0
├── gems/...

The first one is meant as the Lambda code, while second will work as Lambda Layer, allowing you to share it between multiple Lambdas using the same codebase.

Note that:

  1. The structure will be "flattened" (based on contents of the --app-path)
  2. Only gems not in development and test groups will be bundled
  3. The first run might be very long. It requires pulling the base image, building Bundler image, fetching and building gems for your application

Programmatic usage

executor = LambdaRubyBundler::Executor.new(
  '/tmp/my_serverless_app',
  'backend',
  true
)

result = executor.run
File.write('bundle.zip', result[:application_bundle].read)
File.write('dependencies.zip', result[:dependency_layer].read)

Cache mode

The gem can also automatically assign build paths and cache them. To use Cache Mode, simply use --cache-dir option in CLI usage or use LambdaRubyBundler::CLI::CacheRunner class to generate the bundles.

lambda_ruby_bundler --app-path backend --cache-dir tmp

runner = LambdaRubyBundler::CLI::CacheRunner.new(Dir.pwd, 'backend', 'tmp')
runner.run

This will save the bundles in cache directory and will output the paths to STDOUT (CLI case) or return them as Hash (programmatic usage).

Ruby versions

Currently, Lambda supports only Ruby 2.5 environment - specifically, 2.5.5. At the moment of writing this Readme, newest version from 2.5.x family is 2.5.7.

Your application is expected to work properly on Ruby 2.5.5, but the LambdaRubyBundler does not verify it in any way. To ease the development of the application, the ruby entry from Gemfile will be removed while bundling gems, allowing you to develop your application with any ruby version.

Note that it is still best to use a version from Ruby 2.5.x family - other versions might be packaged successfully, but might not work when deployed to Lambda!

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/td-berlin/lambda_ruby_bundler. 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.

License

The gem is available as open-source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the LambdaRubyBundler project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.