⚠️ This boilerplate requires configuration before use!!! Follow the instructions below carefully.⚠️
💰 NOTE: Current running costs are unknown, but I will add these as the data becomes more transparent.
This is a boilerplate Golang, NextJS/React application which features the following:
- Go for all the backend and CDK.
- Middleware pattern and library for lambda function handlers.
- Hexagonal architecture/adapter based for the backend.
- CDK (written in Golang) to deploy the application to the cloud.
- Lambda serverless functions
- DynamoDB tables and triggers with point in time recovery
- KMS encryption
- Cognito User & Identity Pools
- AWS AppSync authorised and unauthorised access via IAM roles.
- Github Actions
- Runs go tests
- Runs frontend tests
- Synthesises & Runs checkov infrastructure as code
- Builds the frontend
- Branch based deployment via CDK to AWS (main, staging)
- Codecov Code coverage for the backend and frontend
- Checkov for infrastructure as code security checks.
- CycloneDX for generating an SBOM
- golangci-lint for static code analysis.
- Pre-Commit for git hook code quality checks.
- NextJS for the frontend.
- Apollo GraphQL
- GraphQL Codegen for generating TypeScript types and Apollo client hooks from our schema automatically.
- GraphQL Linting for static code analysis.
This repository follows these standards for project layout.
TL;DR You'll find:
- Private code in
/internal
- Lambda and other command type functions in
/cmd
- Frontend in
/web
This is a boilerplate for creating a serverless application using the AWS AppSync GraphQL API while using Go for the backend and NextJS for the frontend.
Typical audiences are:
- CTO/CEO looking to save time and money getting a good foundation in place.
- Developers and dev-ops teams looking to get started quickly and cheaply.
- Anyone who wants to get a simple serverless application up and running.
There are a few steps to getting the most out of this boilerplate:
- Installing dependencies
- Adding AWS parameter store values
- Configuring your app
- Deploying to AWS
- Running the frontend
- Testing your app
Before anything, you must have a valid AWS account.
All the AWS services are free for the first year, and you can apply for $300 credit here.
To deploy this, the following parameter store values are required to be readable by a cdk
user.
Substitute {environment}
with any of staging, production, ci
/$APP_NAME/{environment}/GITHUB_ACCESS_TOKEN # Secure String
/$APP_NAME/{environment}/OAUTH_CALLBACK_ROOT # String
- Golang 1.18+
- AWS CLI and AWS vault to setup AWS credentials
- direnv to manage environment variables automatically.
- Pre-Commit for git hook code quality checks to prevent bad commits.
- nodeJS & yarn for managing/running frontend dependencies and aws-cdk for the CDK deployments.
The frontend is based on NextJS and React with TypeScript & Vitest and Cypress for testing.
It uses yarn 2.x for managing dependencies.
Running yarn install
will install all frontend dependencies.
Read More about the frontend.
Go dependencies are managed via Go modules but if you want to download them ahead of time you can run go mod download
to download them.
Edit ./.envrc
and set the following:
APP_NAME # The name of the application (affects import paths, should be the git repo name.)
NGROK_DOMAIN # This is the subdomain on ngrok you'll access the frontend from locally.
AWS_REGION # This is the region you'll be deploying to.
AWS_ACCOUNT_ID # This is the account you'll be deploying to.
GITHUB_ACCESS_TOKEN # This is the access token you'll use to access the GitHub API.
Go to Github and
- Generate a new personal access token for the app here
- Go to repository secrets and add the following:
ENVIRONMENT AWS_REGION AWS_ACCOUNT_ID GITHUB_ACCESS_TOKEN OAUTH_CALLBACK_ROOT CODECOV_TOKEN
You should have the dependencies' installation instructions AND the environmentals instructions completed above to continue, you should be able to run init-project
which will rename this project to match your Git repository name.
The CDK supports creating stacks per any environment, supported environments are production, staging, ci
deploy
Or you can deploy a specific environment with
ENVIRONMENT={production, staging, ci} deploy