Feature Branch Deploys

[alex-bezek]

As a contributor, I want branches to be auto deployed so i can preview my changes prior to merging, so that people can write blogs in markdown without having to run the site locally to preview changes, and so reviewers can see the most up to date changes without relying on old screenshots.

Design Proposal

There are many services and tools available that offer varying out of the box experiences to achieve this.

Other options:

• Netflify: Netflify offers a great out of box full service experience. You can simply point it at a github repo and it will build and deploy any branch you want as well as pull requests. Each deployment gets a unique url and the github app will comment with the link on the PR. You can also integrate custom domain names with free lets encrypt support. While i swear by this service, the free tier only allows a single admin, and the next tier is pretty pricey.
  • Heroku: Heroku also offers a platform as a service experience that allows for configuring similar branch deployments. However, heroku doesn't utilize a static site deployment model, it uses running containers (dynamos). The free tier then limits how long dyanmos can be up during a day. Often times it will sleep so to view it you have to wait 30 seconds for it to spin up the site.
• Github Actions: fairly new on the block, but free and powerful. However, where Netflify is a full service out of the box, github actions would need to be used to stitch together other services as it just offers the compute but not the storage. Github pages can't support more than a single deployment (without some very hacky folder shenanigans). S3 would be a logical service to use for the hosting. There are some hurdles to using it though. For Cerner security compliance, all S3 buckets must be encrypted and not allow public reads to bucket contents. To host a publicly visible site in a bucket then you would need to also configure cloudfront and an OAI on top of the bucket. On top of that, you then have to decide if you want to create a Stack per PR or store each PRs content in a separate folder. The separate folder per PR is cheaper and simpler to implement, but then each PR's site has an extra path in the url. To get around this the jekyll build config would need to parameterize https://github.com/cerner/cerner.github.io/blob/source/_config.yml#L29 to account for loading assets.

Preferred Option:

From a hosting and deployment perspective, AWS Amplify offers almost the same full feature set as Netflify https://aws.amazon.com/amplify/ . To try it out, i implemented it using a fork of the repo https://github.com/alex-bezek/cerner.github.io. Because everything i wanted to do is covered in the free tier, i just used my own aws account for convenience. The steps i took were:

• Create a new Amplify application https://console.aws.amazon.com/amplify/home
• Setup to use github as the source
• Authorized the amplify app to interact with my github org and select the cerner.github.io repository
• selected source as the primary branch to build
• Edit the build settings to the following (the package installs are needed for pygments to work)

version: 0.1
frontend:
  phases:
    preBuild:
      commands:
        - apt-get update -y
        - apt-get install default-jdk -y
        - apt install python-pip -y
        - apt install python2.7 -y
        - apt-get install python-pygments -y
        - bundle install
    build:
      commands:
        - bundle exec rake generate
  artifacts:
    baseDirectory: public
    files:
      - '**/*'
  cache:
    paths: []

• Select Advanced Settings and use https://hub.docker.com/r/artemius/ruby-2.2.3 as my build image. The default build image doesn't support our version of ruby and i didn't want to upgrade everything https://github.com/aws-amplify/amplify-console/blob/master/images/amazonlinux1/Dockerfile#L12
• Save and deploy. This will deploy the source branch.
• Next select "Previews" from the side menu and enable them.
• Select the source branch, click manage, and enable previews for that branch.
• Follow the prompts to install the github application so it can watch for PRs and comment with links to deployments.

Outputs

Primary Branch deployed: https://source.df01c5fpiua30.amplifyapp.com/ Pull Request: https://github.com/alex-bezek/cerner.github.io/pull/1 PR Deploy: https://pr-1.df01c5fpiua30.amplifyapp.com/

Make it real

In order to use it in a production setting, there are some additional things we would want to do

• Codify the configuration via cloud formation templates https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/AWS_Amplify.html
• Create a deployer IAM Role with write permissions to AWS Amplify https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awsamplify.html
• Install the amplify app into the public Cerner github org
• Maybe create our own build container and host it in the Amazon Elastic Container Registry so we don't rely on an old random public image.

Pricing

https://aws.amazon.com/amplify/console/pricing/

Because it's just managing static assets, the pricing is very reasonable. At 1000 free build minutes per month, and our current build taking only 7 minutes (which could be reduced much further with a custom container with packages pre-installed) we likely would never pass this (we would need over 140 builds in a month).

Future thoughts

While not in scope for this issue, amplify could be used to automate the deployment of the primary branch instead of using github pages. While it is probably less work to just setup a github action to deploy the source branch, it would be nice to only manage a single method of deployments. A couple of other minor benefits are

• Github pages has limitations around its usage https://help.github.com/en/github/working-with-github-pages/about-github-pages#usage-limits . Most likely we are no where near the bandwith limits. The site size limit is 1gb, and while we are only at ~225mb, images add up over time
• Public github pages do not offer any SLA uptime i can see, while AWS services do
• Amplify fronts its s3 bucket with cloudfront giving us a CDN.

[alex-bezek]

We've discussed this amongst a few of us and amplify seems like a good fit, but we wanted to put this proposal out here to discuss more and see if there are any other opinions.

[mjhenkes]

Terra does this for free with heroku review apps: https://devcenter.heroku.com/articles/github-integration-review-apps

Which you stated above, but it's been working out for us.

[alex-bezek]

Thanks @mjhenkes . Looking at the free tier it does allow up to 5 team members which would probably be plenty for this group. Netfliy's issue was the free tier only allowed a single member.

Admittedly I'm a bit biased against heroku for deploying static sites since i'm used to using other static deployment tools like netlify and zeit. Heroku utilizes containers so my understanding is you have to build your statics and run them in a simple server so there are quirks like having to deal with those containers going to sleep and spinning back up when requested. Static site deployments have some minor other niceties like immutable deploys so you can compare the current vs the old deploys that never disappear.

These are pretty minor things though, especially with the amount it would be used for this repo, so if the fact that it's super easy to setup and the terra team uses it already, it might be worth considering more heavily.

[alex-bezek]

Another option we are talking about is having an internal fork and utilizing an internal bot that does internal branch deploys to jenkins workspaces. This would be a side-affect of solving this problem https://github.com/cerner/cerner.github.io/issues/135 that way

[mjhenkes]

I poked around at setting this up on heroku for you, but your version of ruby is way too old to build on heroku. You'd have to at a minimum do issue https://github.com/cerner/cerner.github.io/issues/108 before it would work.

[cchesser]

These changes have been applied to #136. We should be able to close this out once #136 is finished.

[cchesser]

Changes have been merged into source: 1a72b67a1b0fd61b27e9ac4cc312a9dadbf1f7e8