Trellis

An open-source deployment pipeline tool built for serverless applications

Trellis is built to give teams a low-configuration deployment pipeline for their serverless applications which are deployed to AWS. Trellis itself is a serverless application, deployed on the users's own AWS infrastructure. Trellis handles the provisioning and management of development, staging and production environments for serverless applications.

Find more about the details of Trellis by reading our case study

Features

• Trellis provisions deployment environments for serverless applications built on AWS
• Deployment environments can be automatically provisioned from commits to connected GitHub branches
• Code is promoted to staging and production environments manually, and can be rolled back as well
• Trellis provides a dashboard for managaing deployment pipelines

How Trellis Works

Trellis is itself a serverless application, and can be deployed to AWS with a single command. Users then create a Trellis application and connect it to their target GitHub repository. Trellis is composed of a React dashboard, a backend mostly composed of AWS Lambda functions and an on-demand build server run using AWS Elastic Container Service.

A webhook is registered on the target GitHub repository. Commits to that repository trigger the provision of an ephemeral build server which deploys the users application on AWS infrastructure. Users can log in to the Trellis dashboard to view the state of their deployments, or to trigger manual promotions, rollbacks or teardowns of deployment environments.

Technology

• AWS CDK and SDK
• Serverless Stack (SST) Framework
• AWS Lambda, ECS, Fargate, DynamoDb
• Node.js and React

The Team

Marco Avila Software Engineer New York, NY

Mohamad El-Chanti Software Engineer Toronto, ON, Canada

Martin Graham Software Engineer Waco, TX

Cody Williams Software Engineer Los Angeles, CA

Installation

Clone Trellis

1. git clone https://github.com/Trellis-Deployment/trellis.git
2. Enter the cloned directory and rename the .env.template to .env
   • cd trellis
   • mv .env.template .env
3. Install the package dependencies
   • npm install

Create a GitHub app

1. Create a GitHub app to interact with trellis

   1. Sign into github.com
   2. Settings --> Developer Settings link
   3. Go to GitHub Apps --> New GitHub App
   4. Name the app (we suggest including the word Trellis)
   5. Put any name in the Homepage URL field
   6. Check Request user authorization (OAuth) during installation
   7. Check 'Enable Device Flow'
   8. We will be returning here to fill out the callback and setup URLs
   9. Permissions
      • Repository Permissions
        • Checks - Read and Write
        • Commit statuses - Read and Write
        • Contents - Read
        • Deployments - Read and Write
        • Metadata - Read
        • Pull Requests - Read and Write
        • Webhooks - Read and Write
      • Account Permissions
        • Email addresses - Read
   10. 'Where can this GitHub app be installed?' - select 'Any account'
   11. Click 'Create GitHub App'
   12. In the .env file in the trellis directory, copy the following information from your GitHub app
       • App name
       • ClientId
   13. Click on 'Generate a new client secret' - Copy this secret into your .env file

Install the AWS CLI

1. Install the AWS CLI and configure your credentials - these are used to deploy Trellis on your AWS account

Push the build server docker image to ECR

1. Next we need to locally build the docker image used to run deployments and push it to ECR
2. In the docker-container directory there is a script called build-and-push-to-aws.sh that will build an image and load it to AWS ECR.
3. The script uses the AWS CLI to get your AWS account number, and defaults to the region 'us-east-1' - change these values in the script if you so desire
4. Make the /docker-container/build-and-push-to-aws.sh executable with chmod a+rx build-and-push-to-aws.sh
5. run ./build-and-push-to-aws.sh
6. If you like, go to ECR in the AWS console and verify the container exists

Deploy Trellis

1. Return to the root directory of the project, then run npx sst deploy to deploy Trellis on your AWS infrastructure
2. Copy the site URL that is logged during the deploy - return to the GitHub app settings from earlier
   • Copy this url into the Callback URL and append /gitRedirect
   • Copy this url into the Setup URL and select Redirect on update

License

MIT License

Copyright (c) 2022 Aria

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.