| Branch | Build Status |
|---|---|
| main |  |
| val |  |
| production |  |
RHTP is the CMCS MDCT application for collecting state data related to the Rural Health Transformation Program (RHTP).
Team members are encouraged to setup all MDCT Products using the script located in the MDCT Tools Repository. Please refer to the README for instructions running the MDCT Workspace Setup. After Running workspace setup team members can refer to the Running the project locally section below to proceed with running the application.
If you have run the MDCT Setup Script this section can be skipped
Before starting the project we're going to install some tools. We recommend having Homebrew installed if you haven't already to install other dependencies. Open up terminal on your mac and run the following:
-
(Optional) Install Homebrew:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -
Install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash -
Install specified version of node. We enforce using a specific version of node, specified in the file
.nvmrc. This version matches the Lambda runtime. We recommend managing node versions using NVM:nvm install, thennvm use -
Install pre-commit on your machine with either:
pip install pre-commitorbrew install pre-commit
If you have run the MDCT Setup Script this section can be skipped
- Clone the repo:
git clone https://github.com/Enterprise-CMCS/macpro-mdct-rhtp.git - Ensure you either have a 1Password account and have 1Password CLI installed. Alternatively, reach out to the team for an example of .env files
- In the root directory run
pre-commit install
In the root of the project run ./run local --update-env to pull in values from 1Password and run the project. Alternatively, if you do not have a 1Password account you will need to reach out to an MDCT team member for values for your .env . Then you can run ./run local to use a static manually populated .env file.
(Make sure you've finished setting up the project locally above before moving on to this step!)
Once you've run ./run local you'll find yourself on a login page at localhost:3000. For local development there is a list of users that can be found at services/ui-auth/libs/users.json. That's where you can grab an email to fill in.
For a password to that user, please ask a fellow developer.
With the app running, you can navigate to the Localstack Dashboard and sign in using your GitHub account (or whatever you prefer) to view local insfrastructure, such as database tables, S3 buckets, and api logs.
As an alternative to Localstack, you can interact with just the database using dynamodb-admin.
In order to run DynamoDB locally you will need to have java installed on your system. The MDCT Workspace Setup script installs that for you.
If you cannot run the MDCT Workspace setup script see below for manual instructions:
M1 Mac users can download java from azul. Note that you'll need the x86 architecture Java for this to work. You can verify the installation with java --version. Otherwise install java from here.
To view your database after the application is up and running you can install the dynamodb-admin tool.
- Install and run
DYNAMO_ENDPOINT=http://localhost:4566 dynamodb-adminin a new terminal window
Local dev is configured as a Typescript project. The entrypoint in ./src/run.ts manages running the moving pieces locally: the API, database, filestore, and frontend.
Local dev is built around the cdk setup which gets run locally by Localstack.
Local authorization uses Cognito from the main stack in dev. The credentials are injected locally by the ./run update-env command which fetches values from 1password and puts them into a gitignored .env file.
We use Vitest for unit tests.
To run all frontend unit tests:
cd services/ui-src/
yarn test
To run all backend unit tests:
cd services/app-api/
yarn test
In either of these directories you can also check code coverage with
yarn coverage
Tests automatically live reload and rerun until you exit the command.
We use axe and pa11y for primary accessibility testing.
Unit tests use jest-axe
This repo uses the code formatter oxfmt. The formatter is run automatically in a pre-commit hook. Additionally, oxfmt can be run on file save in many IDEs or run ad hoc from the command line.
The oxc extension can be downloaded from the VS Code Marketplace.
Once installed, open VS Code's Preferences. Search for "Format on Save". Clicking the checkbox should engage the oxfmt formatter on file save.
VS Code is used almost ubiquitously across the current development team, generally speaking this tools should also work for most other IDEs.
Using this command, or a variant of it, will format all matching files in the codebase and write the changes. oxfmt has complete CLI documentation on their website.
yarn oxfmtAll changed files will also be checked for formatting via the pre-commit hook.
oxlint works in a similar manner to oxfmt for all code linting.
yarn oxlint --deny-warningsOn a push to the repository or opening a pull request the deploy.yml file runs. This script sets up and does a number of things. For a simple push it's mostly checking code coverage.
This application is built and deployed via GitHub Actions.
Please Note: Do Not Squash Your Merge Into Val Or Prod When Submitting Your Pull Request.
We have 3 main branches that we work out of:
- Main (Pointed to https://mdctrhtpdev.cms.gov/) is our development branch
- Val (Pointed to https://mdctrhtpval.cms.gov/) is our beta branch
- Production (Pointed to http://mdctrhtp.cms.gov/) is our release branch
When a pull request is approved and merged into main the deploy script will spin up and upon completion will deploy to https://mdctrhtpdev.cms.gov/. If a user wants to deploy to val they can initiate the Create Deployment PR action in GitHub actions, setting the target_branch variable to the destination environment. Once that pull request is approved, the deploy script will run again and upon completion will deploy to https://mdctrhtpval.cms.gov/. So to quickly break it down:
- Submit pull request of your code to main
- Approve pull request and merge into main
- Deploy script runs and will deploy to https://mdctrhtpdev.cms.gov/
- Create Deployment PR action into val
- Approve pull request and DO NOT SQUASH YOUR MERGE, just merge it into val
- Deploy script runs and will deploy to https://mdctrhtpval.cms.gov/
- Create Deployment PR action into production
- Approve pull request and DO NOT SQUASH YOUR MERGE, just merge it into production
- Deploy script runs and will deploy to http://mdctrhtp.cms.gov/.
If you have a PR that needs Product/Design input, the easiest way to get it to them is to use the cloudfront site from Github. Go to your PR and the Checks tab, then Deploy tab. Click Summary and you will find the cloudfront URL in the deploy summary (once that step completes).
RHTP pipes updates from the report object tables to BigMac for downstream consumption. To add a topic for a new report type, update the following locations:
deployment/topics.ts- Any new table with come with streaming (tables are defined here:
deployment/data.ts)
- Any new table with come with streaming (tables are defined here:
services/app-api/handlers/kafka/post/postKafkaData.ts- Add the bucket and table names into the appropriate arrays. They will be parsed with their event types accordingly.services/topics/createTopics.js- Declare the new topic names. Both the stream name for the bucket and table should be added here.
- Secrets are added to GitHub secrets by GitHub Admins
- Development secrets are maintained in a 1Password vault
See LICENSE for full details.
As a work of the United States Government, this project is
in the public domain within the United States.
Additionally, we waive copyright and related rights in the
work worldwide through the CC0 1.0 Universal public domain dedication.