@docs-gov-sg/doc-theme-default v0.0.11

Deployment

Creating a new environment

1. Use EB CLI to deploy application instances into VPC.

eb create <env name> \
  --vpc.id <VPC ID> \
  --vpc.dbsubnets <private subnet 1, private subnet 2> \
  --vpc.ec2subnets <public subnet 1, public subnet 2> \
  --vpc.elbsubnets <public subnet 1, public subnet 2> \
  --vpc.securitygroup <sec group id 1, sec group id 2>

2. Create RDS instance in same VPC.

3. Configure environment variables needed by application in EB console: app url, DB things, TechPass OIDC params, GitHub Oauth params, SNS topic ARN.

4. Fix custodian - ELB security groups and EC2 offline hours.

5. Configure VPC security groups -

6. Create corresponding lambda (serverless deploy) for handling GitHub push events, using SNS topic as defined in EB environment.

7. Create IAM role specifically for application EC2 instances to connect to DB, S3, SNS etc. Change EB environment instance config to reflect this.

8. Obtain certs from ACM for desired domain and attach to ALB.

IAM

CI Deployers must have corresponding permissions for creating DynamoDB, S3, SNS and Lambda resources.

Elastic Beanstalk components

DynamoDB, S3, SNS resources are defined as Elastic Beanstalk resources.

GitHub webhooks hit the application which sends a push topic to SNS.

A Lambda function listens to the SNS topic, defined in serverless.yml.

To run the app locally, set up a Elastic Beanstalk local environment:

eb init
eb create $MY_ENVIRONMENT
eb deploy

To deploy the SNS subscriber Lambda, use Serverless framework:

serverless deploy --stage $MY_STAGE --aws-profile $MY_PROFILE_NAME

The app will reference these tables through environment variables. For example:

# .env, or use environment variables
NODE_ENV=local
APP_TABLE="doc-portal-$NODE_ENV"
SESSION_TABLE="doc-portal-sessions-$NODE_ENV"

Serverless components

Serverless framework is used to define a lambda function that listens to the SNS topic defined in the Beanstalk application. This lambda listens for GitHub push events which are generated by the Beanstalk application.

The serverless service must have its name synced up with the Beanstalk environment:

Running in dev machine

Set up environment variables in the .env file, then run two shells to do real-time builds of both static (Vue) and backend (express) apps.

npm run dev:server
npm run dev:static

AWS resources for local development

Pass environment variables into the application through the .env file.

Receiving GitHub webhooks locally

Use ngrok to test webhooks from GitHub locally, by setting GIT_SOURCE_WEBHOOK_URL in .env.

Testing SNS pub/sub locally

A full Dynamo/SNS/S3 environment is needed for the SNS lambda listener.

Resources for local development are defined at cloudformation/local-resources.yml. To set up:

serverless deploy --aws-profile $MY_PROFILE_NAME --config cloudformation/local-resources.yml

The function at lambda/gitPush.js will be subscribed to the local SNS topic.

The local running application will push to that SNS topic. Do set this from the GIT_PUSH_TOPIC_ARN environment variable in .env or otherwise.

Debug as needed through CloudWatch.

Remove Serverless components

serverless remove --stage $STAGE --aws-profile $MYAWSPROFILE