Template

This is a template repo to get you started building services from a common baseline.

Overview

This repo implements:

• Frontend (Cloudfront - modify the contents of /web/public to update the frontend)
• Lambda (API - modify /api/src/routes.ts to build an API)
• AWS CLoud Development Kit (CDK) infrastructure as code - modify .infrastructure/lib/*.stack.ts and run the deploy.sh script
• Scloud constructs and Scloud Github Actions integration in the infrastructure code

Getting started

Prerequisites

• A domain is required to provision SSL certificates. You'll need either a domain name in Route53 with an accompanying hosted zone, or the ability to update name servers for a domain to point to a zone file you will create/have created in Route53.
• A Github personal access token with "repo" permissions

Setup

• Clone this repo and rename the directory from template to the repo name you'd like to use. If you already have a repo, you can change the remote to point to that, or you can simply copy generated files to your repo
• If you're using an AWS profile, set the AWS_PROFILE environment variable to have this configured in the deployment.
• Run ./setup.sh to generate and set up a template CDK infrastructure (the CDK stack will be named to match the name of the current directory, which is the reason to rename it in the first step)
• edit the generated *.sh files under .infrastructure/secrets/
  • set the domain name and optionally zone ID if using a pre-existing zone (recommended)
  • set your Github details including a personal access token, which will need to have 'repo' scope
• edit .infrastructure/lib/<name>-stack.ts
  • If your AWS account already has an OpenID Connect provider (e.g. if other stacks are deployed to this account) you will need to comment out the githubActions(this).ghaOidcProvider(); line in .infrastructure/lib/*-stack.ts. You can check if there's already a provider by going to IAM -> (left menu) Access Management -> Identity providers. If there's an entry for token.actions.githubusercontent.com then you'll need to comment out the line in the stack code. The provider enables keyless login from Github Actions to AWS for deployment.
  • Delete any other placeholder code you don't need and tidy up linting errors
• From the .infrastructure directory run ./deploy.sh to deploy the infrastructure
• Once you're up and running, /setup.sh and the /setup direcory can be deleted

Infrastructure checklist

• .infrastructure/secrets/github.sh - set username/owner, repo (all case-senditive) and access token.
• .infrastructure/secrets/domain.sh - set domain name and hosted zone ID. (and maybe deleted Cognito domain prefix)
• .infrastructure/lib/*-stack.ts - If OIDC provider is already configured, comment this out. Delete whatever's not needed. Degive whether to use WebRoutes or just a WebApi if no website is needed.

Key files

Temporary setup files - can deleted once complete:

• setup.sh and setup/*: set up the infrastructure
• app/setup/*: set up the app

Files of interest

• .infrastructure/lib/*-stack.ts: infrastructure code - will be generated by setup.sh
• api/src/routes.ts: route definitions for the API component (note that, for clarity, all paths are absolute, i.e. the full path from the URL)
• upgrade: upgrade global and local dependencies - you may need to edit this to fit your structure
• .easignore: ignore everything except the app directory when uploading to EAS to build the app

Development

• Make the changes you need
• Check in and push to Github
• Check the build runs successfully via the "Actions" tab on Github
• Your changes should now be deployed to AWS and visible via your domain over https