Quick Start

A new Rails application deployed to AWS Lambda Containers in a few minutes!

Lamby can be used with existing or new Rails/Rack applications. The quickest way to deploy a new Rails application on AWS Lambda is to use our cookiecutter project template. A few console commands will have you up and running in a few minutes!

Before you get started, make sure you have Docker installed.You will also need an AWS Account. If you are deploying your Rails application from your own computer, you will need the AWS CLI installed and configured. However if you plan to use Lamby's built-in GitHub Actions you will need to configure AWS secrets.

If any of these tools or AWS Lambda are completely new to you, consider learning how to install Docker, setup an AWS Account, and how Ruby & Lambda work by using this excellent Ruby AWS Lambda Microservice Workshop links above. Otherwise, let's get started.


New Rails Application

The AWS SAM CLI allows you to initialize a new project from a GitHub repository template, commonly called a cookiecutter. Assuming you want to use the full Docker solution that avoids needing to install SAM locally, use this command.

$ docker run \
  --rm \
  --interactive \
  --volume "${PWD}:/var/task:delegated" \
  public.ecr.aws/sam/build-ruby2.7 \
  sam init --location "gh:customink/lamby-cookiecutter"

If you have the SAM CLI installed on your system, you can use this command.

$ sam init --location "gh:customink/lamby-cookiecutter"

Bootstrap & Setup

The cookiecutter install would have prompted you for your application's new name. This guide will assume my_awesome_lambda was used. All commands below assume you have changed to that working directory.

$ cd my_awesome_lambda

Lamby's cookiecutter project encourages the use of a normalized script pattern when working with projects. These two commands will bootstrap and setup your system. Typically bootstrap is a one time process where as setup is often run when dependencies change.

$ ./bin/bootstrap
$ ./bin/setup

These scripts typically build a Docker development image and bundle gems. We also do some work to ensure an ECR Repository is created for your later container deployments.

First Deploy!

Now your Rails application is ready to be deployed to AWS Lambda via SAM which is pre-packed in your development container. We make this easy by using a single script which builds, packages, and deploys your Rails application via AWS SAM using a CloudFormation stack to create all your AWS resources as defined in your project's template.yaml file.

$ ./bin/deploy

When run locally, this script will leverage your local AWS CLI credentials which are shared with the development container. If needed you can prefix the deploy script with the AWS_PROFILE environment variable to target a non-default AWS credentials. ⚠️ When deploying from your own machine, you must reset your local environment by using ./bin/setup after each deploy.

CloudFormation outputs from deployed stack
Key           MyAwesomeLambdaHttpApiUrl
Description   Lambda Invoke URL
Value         https://7m473epf5f.execute-api.us-east-1.amazonaws.com/production/

During the end of this process, you will see SAM output similar to what is shown above. This is an API Gateway HTTP API endpoint which invokes your Rails application using Rack. Load it up in your browser and you should see the familiar welcome to Rails screen. 🎉🎉🎉

Yay! You're on Rails with AWS Lambda Containers

Deploy with GitHub Actions

⚠️ If you ran the deploy command above from a Mac, you may have noticed it took 15 minutes or more to complete. This is due to a long standing Docker for Mac filesystem bug that will likely never be fixed.

Good news! The Lamby starter includes two GitHub Actions workflows to encourage good CI/CD practices. One to run your tests, and another to deploy your application. Both include caching and since Docker on Linux is much faster, deploys typically happen in 4 minutes or less. Here is a quick guide on how to set that up.

  1. Create a new GitHub Repository and push your project to it.
  2. Using IAM within the AWS Console, create a deploy user with the necessary AWS managed policies and programatic access. Take note of the user access key id and secret credentials. ⚠️ You will also need the AWSCodeDeployFullAccess managed policy.
  3. Within your project's GitHub repository add two Encrypted Secrets using the credentials values above with the environment names of AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
  4. If needed, change the aws-region in your .github/workflows/deploy.yml file from us-east-1 to your own region.
  5. Trigger a deploy by navigating to the Deploy workflow and clicking "Run workflow".

Lambda & Rails deploy with GitHub Actions

What Just Happened?

You just deployed a new Rails v6 application to AWS Lambda Containers using an AWS Ruby 2.7 base image. This project has everything you need for a server-side API and/or a client JavaScript application. Please take some time to explore your Rails app and how Lamby works in the next section.