Bin Scripts (Build & Deploy)

Our Quick Start cookiecutter includes a single bin/deploy script that wraps three SAM commands needed to deploy your application.

• sam build
• sam package
• sam deploy

Think of our provided bin scripts as starting points! You should add to or adjust each to meet your needs. From a Lamby perspective, here are a few helpful topics about our deploy process and other options you may need.

• Overview of Deploy Process
• Using Private Gems on GitHub
• ECR Repository
• Multiple Environments
• Permissions Needed
• Deploy with GitHub Actions

Overview of Deploy Process

The Lamby deploy process is tightly coupled to using Docker images for development, test, and deployments. We leverage the AWS SAM build images which are much larger than the production runtime images since they include common build tools. In general the process is:

• Cleans the vendor/bundle directory for deployment bundle.
• Performs a bundle install for production.
• Retrieve secrets from SSM Parameter Store. Writes to a Dotenv file.
• Precompiles static CSS & JavaScript assets.
• Copies your project to a base Lambda Container image via AWS SAM.
• Pushes your final image to ECR with AWS SAM.

⚠️ When deploying from your own machine, you must reset your local environment by using ./bin/setup after each deploy. It is recommended that you use a CI/CD pipeline such as GitHub Actions as described in our Quick Start section.

Using Private Gems on GitHub

Our current starter shares your ~/.aws directory with the dev/build image to facilitate local deployments. Depending on your needs, accessing private dependencies for both local development and CI/CD pipelines will require additional code.

Please see this post titled Serverless Docker Patterns which has a section called Cross-Platform SSH Agent for CI/CD that outlines a simple process using docker compose and GitHub Actions.

ECR Repository

Lamby focuses solely on the Lambda Containers package format. Our ./bin/bootstrap script will leverage the AWS CLI to create an Amazon Elastic Container Registry (ECR) repository for your deployed images. At some point in the near future AWS SAM will do this automatically for us.

Multiple Environments

Feel free to make more per-environment deploy scripts or CI/CD workflows. For example bin/deploy-staging may look like this where leveraging your local AWS_PROFILE environment variable. Our starter passes both AWS_PROFILE and RAILS_ENV via our docker compose scripts.

#!/bin/bash
set -e
export AWS_PROFILE="staging"
export RAILS_ENV="staging"
./bin/deploy

For GitHub Actions, you could setup additional workflows or extend the existing deploy workflow to use branch conditions and/or extra GitHub Secrets to a different deploy user in another AWS account.

Permissions Needed

In order to have our deploy scripts work, you must have permission to create the needed Resources and IAM Roles/Permissions for your application to work. Most hobby users have admin level access to their own AWS account. If this is not the case, please consider starting with AWS SAM's recommended permissions needed for deploying functions. We also cover this in our Deploy with GitHub Actions section of our quick start guide.