README
¶
CMS EASi Application
This repository contains the application code for CMS EASi (Easy Access to System Information).
This application has the following main components:
- A React frontend, using Apollo.
- A Go backend that provides REST and GraphQL APIs.
- A Postgres database.
- A few lambda functions for PDF generation and file upload virus scanning.
Documentation
- Program Background
- Development environment setup
- Contributing
- Architecture Decision Records (ADRs)
- Frontend docs
- Backend docs
- Running development tasks with
scripts/dev- includes instructions on running the application locally - GraphQL development
- Working with the database - includes instructions on modifying the database schema
- Testing locally
- Docker Compose files and usage
- Deployment Process
- Interacting with CEDAR - CEDAR is a CMS system whose API we interact with; this includes instructions on how to connect to it
- Security Policy
Repository Structure
This repository has several major subfolders:
.githubcontains GitHub-related configuration; notably,.github/workflowscontains the workflow definitions for CI/CD through GitHub Actions..storybookcontains configuration for Storybook, which can be used for viewing and designing React components in isolation..vscodecontains settings and suggested extensions for developing in VS Code.cmdcontains Go CLI scripts for various utilities.config/tlscontains certificates that need to be trusted by the EASi backend.cypresscontains end-to-end/functional tests using [Cypress][https://www.cypress.io/], as well as necessary configuration.docscontains general documentation for the EASi application; thedocs/adrsubfolder contains records of architectural decisions, whiledocs/operationscontains information on operational procedures such as deploying the application.migrationscontains SQL files that together define the database schema; these are deployed using Flyway.pkgcontains the Go source code for the application's backend.publiccontains static assets for the frontend.scriptscontains Bash and Ruby scripts used for various development and operational tasks.srccontains the TypeScript source code for the application's React frontend.
Optional Setup
LaunchDarkly
The app uses LaunchDarkly to control feature flags in deployed environments. By default the application run in offline mode and uses default values for all flags. To enable loading the flags from LaunchDarkly, add the following to .envrc.local:
export LD_SDK_KEY=sdk-0123456789
export FLAG_SOURCE=LAUNCH_DARKLY
These values can be obtained from the LaunchDarkly settings page or from 1Password.
To modify the default flags being used, edit src/views/FlagsWrapper/index.tsx. In the call to asyncWithLDProvider() inside useEffect(), modify the values being passed as the flags option.
1Password
See also: ADR on how we share secrets
Truss have set up a 1Password vault for EASi engineers to securely share secrets, such as API keys. You will need to be invited to generate login credentials.
If you need access to a secret that is not in the EASi vault, please ask for someone to add it to the vault.
Cloud Services
You may need to access cloud service to develop the application. This allows access to AWS resources (ex. SES Email).
Follow the instructions in the infra repo
here. You'll need to add
the infra account environment variables to your .envrc.local. You can then run
the ctkey command to get/set AWS environment variables.
https_proxy=localhost:8888 \\
ctkey --username=$CTKEY_USERNAME \\
--password=$CTKEY_PASSWORD \\
--account=$AWS_ACCOUNT_ID \\
--url=$CTKEY_URL \\
--idms=$CT_IDMS \\
--iam-role=$CT_AWS_ROLE setenv
Eventually, we will move this over to wrapper so developers do not need to manually run these commands.
Development and Debugging
(#authentication)
Authentication
The application has two authentication modes. The main mode is to use Okta to authenticate using hosted services. The second is to use a local-only login mode that avoids this network dependency.
To sign in using local mode, Click the Use Local Auth button on the sign in page. This is only provided when running the app locally.
To enable Okta authentication locally, add the following values to
.envrc.local:
export OKTA_TEST_USERNAME=
export OKTA_TEST_PASSWORD=
export OKTA_TEST_SECRET=
These values can be found in 1Password under "CMS IDM Test Account".
Routes Debugging
Setting the DEBUG_ROUTES environment variable, and upon startup, this will log
out a representation of all routes that have been registered.
$ DEBUG_ROUTES=1 ./bin/easi serve
...
ROUTE: /api/v1/healthcheck
Path regexp: ^/api/v1/healthcheck$
Queries templates:
Queries regexps:
ROUTE: /api/graph/playground
Path regexp: ^/api/graph/playground$
Queries templates:
Queries regexps:
...
Minio
MinIO is an S3 compatible object store. It ships as a Docker container and accepts normal AWS S3 API requests. This allows us to test file uploading functionality in our local development environments without needing to interact with CMS AWS accounts.
The container is configured as part of our docker-compose.yml and should be
running when you scripts/dev up.
The container is accessed from the browser using the hostname minio. To make
this work, run scripts/dev hosts:check and press enter to setup this hostname
on your machine.
You can use scripts/dev minio:clean, scripts/dev minio:infected, or
scripts/dev minio:pending to modify the virus scanning status of files in
minio during development.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
backfill
command
|
|
|
backfill_cedar_intake
command
|
|
|
devdata
command
|
|
|
easi
command
Package main is the entrypoint for command line execution of the easi tool
|
Package main is the entrypoint for command line execution of the easi tool |
|
easi/test
Package test is for test CLI tool execution logic
|
Package test is for test CLI tool execution logic |
|
gen_intake_schema
command
|
|
|
migrate_intakes
command
|
|
|
populate_user_table
command
|
|
|
test_cedar_intake
command
|
|
|
test_email_templates
command
|
|
|
pkg
|
|
|
cedar/intake
Package intake serves as an Anti-Corruption Layer (in Domain Driven Design parlance), keeping the implementation details of working with the downstream CEDAR Intake API well separated, so the rest of the internal workings of the EASi code are not using anything defined by the external API
|
Package intake serves as an Anti-Corruption Layer (in Domain Driven Design parlance), keeping the implementation details of working with the downstream CEDAR Intake API well separated, so the rest of the internal workings of the EASi code are not using anything defined by the external API |
|
logfields
Package logfields provides a standard location for field names we expect in logs
|
Package logfields provides a standard location for field names we expect in logs |
|
pubsub
Package pubsub provides a lightweight, thread-safe publish-subscribe service for managing event notifications within sessions.
|
Package pubsub provides a lightweight, thread-safe publish-subscribe service for managing event notifications within sessions. |
|
scheduler
scheduler contains the logic for scheduled tasks that run in the main thread of the EASI application
|
scheduler contains the logic for scheduled tasks that run in the main thread of the EASI application |
|
scheduler/timing
Timings purpose is to provide reusable definitions for jobs that can be shared whenever a scheduled job is defined
|
Timings purpose is to provide reusable definitions for jobs that can be shared whenever a scheduled job is defined |
|
server
Package server is for setting up the server.
|
Package server is for setting up the server. |
|
sqlutils
Package sqlutils contains functionality to wrap existing database functionality
|
Package sqlutils contains functionality to wrap existing database functionality |
|
testconfig
Package testconfig provides a reusable configuration shared when unit testing multiple packages.
|
Package testconfig provides a reusable configuration shared when unit testing multiple packages. |
|
testconfig/dataloadertestconfigs
Package dataloadertestconfigs provides utility functions for injecting dataloaders into test code
|
Package dataloadertestconfigs provides utility functions for injecting dataloaders into test code |
|
testconfig/dbtestconfigs
Package dbtestconfigs provides helper functions for reusing db test code
|
Package dbtestconfigs provides helper functions for reusing db test code |
|
testconfig/emailtestconfigs
Package emailtestconfigs provides shared utilities when you need to do local testing that requires email configuration
|
Package emailtestconfigs provides shared utilities when you need to do local testing that requires email configuration |
|
testconfig/uploadtestconfigs
Package s3testconfigs is a utility package that allows us to easily configure test S3 clients
|
Package s3testconfigs is a utility package that allows us to easily configure test S3 clients |
|
testconfig/useraccounthelperstestconfigs
Package useraccounthelperstestconfigs provides utility functions for getting user accounts using the user helper package
|
Package useraccounthelperstestconfigs provides utility functions for getting user accounts using the user helper package |
|
testconfig/useraccountstoretestconfigs
Package useraccountstoretestconfigs provides utility functions for getting user accounts using the storage package
|
Package useraccountstoretestconfigs provides utility functions for getting user accounts using the storage package |
|
testhelpers
Package testhelpers is for test code that needs to be imported across packages DO NOT use this in production code
|
Package testhelpers is for test code that needs to be imported across packages DO NOT use this in production code |