j40-cejst-2/docs/operations/rollout-plan.md

# v2.0 Rollout Plan (DRAFT, DELIBERATIVE, PRE-DECISIONAL)

In late 2024, we will release a new version of the CEJST website. This
document describes the process of getting that data and the latest version
of the website released.

The architecture of the site is better described in
[../architecture/README.md](../architecture/README.md), but for the purpose of
this document, we'll just mention that the data for the site is in a "backend"
S3 bucket where the map tiles describing the districts have been generated by
a Python-based data pipeline. That S3 bucket has a Cloudfront distribution in
front of it and is accessible at static-data-screeningtool.geoplatform.gov.
The frontend application uses that URL and some path configuration information
to provide the correct data.

The frontend application is a static site built by Gatsby in a Github Action
then deployed to and served from an S3 bucket behind a Cloudfront distribution at
screeningtool.geoplatform.gov.

## Backend Data Rollout

The CEJST data is stored in an S3 bucket under "versioned" paths (we think)
using `1.0/` in the path. When we build the updated data pipeline for CEJST
2.0, we will configure it to export the files into the existing bucket under
paths marked `2.0/`. The hypothesis is that this will give an updated version
of the CEJST data in that bucket without affecting the data being served by
the existing website

TODO: Validate the hypotheses that
  - [X] the frontend website pulls its backend data from versioned paths
  - [X] the data pipeline that builds the backend data can be configured
    so that it will not overwrite any of the existing data in the same
    bucket

The deploy-backend-main.yml Github workflow builds the scoring and deploys
it to the S3 data bucket. We want to have control of when that workflow runs
so that there are no inadvertent changes to the scoring in the bucket. When
we want to run the build and deploy workflow for the scoring, we can do
so by clicking the button in the Github web UI.

The rollout sequence will be (1) freezing the code in `data/` with the final
v2 changes, then (2) analyzing the resulting changes from v1 to v2 in order to
fully bless the v2 results. Once the analysis and approval is complete we can
(3) run the backend build and deploy workflow to install the final version of
the CEJST scores on the S3 data bucket.

## Frontend app rollout

Rather than trying to incrementally change the frontend app that is deployed
at screeningtool.geoplatform.gov, we will deploy the new 2.0 version of the
frontend website in a new S3 bucket with a new Cloudfront distribution, and
configured to use the new backend data under the `2.0/` paths. This
will allow us to test the deploy process, website improvements, and the
display of the updated data using a staging URL like
<random-string-of-letters>.cloudfront.net.

TODO: Get new AWS resources
  - [X] A new website S3 bucket
  - [X] A new Cloudfront distribution that serves that S3 bucket

After the v2 backend is frozen, approved, and deployed, we will move on
to testing the frontend with that data at the staging URL.

## Release day

When the 2.0 CEJST is ready to release to the public, we can change the
screeningtool.geoplatform.gov domain name to point to the new frontend
Cloudfront distribution instead of the one that it currently goes to. With
this one change, after the DNS change propagates, users online will see the
new frontend website which is configured to display the new backend data.