- Online Application for the Illinois Child Care Assistance Program (CCAP)
- About GetChildCareIL
- I. Local development set up instructions
- II. Development
- III. Cloud infrastructure
Get Child Care IL (abbreviated as IL-GCC) allows families in Illinois to apply online for the Child Care Assistance Program (CCAP). CCAP is a benefit program funded by the Illinois Department of Human Services (IDHS) that helps cover the cost of child care, with eligibility based on income level and family size.
When a family is approved for CCAP, IDHS pays their child care provider(s) directly, to subsidize some or all of the cost of their children’s care. Examples of CCAP providers include daycare centers, afterschool programs, or care from a friend or family member.
Families apply through the site by answering questions and uploading supporting documents. Once a family has submitted their application, they are prompted to notify their chosen child care provider(s). The provider(s) can use the app to reply to the family's request for care, fill out their respective info, and register as a new CCAP provider if applicable. The provider's information is added to the family's application, after which the combined application (containing both the family and provider data) along with all submitted supporting documents are transmitted to the State of IL's Child Care Management System (CCMS) via an API request.
From there, the application will assigned to a dedicated Child Care Referral and Resource (CCR&R) agency for processing and eligibility determination.
This application is a Java Spring Boot application built on Code for America's open source Form Flow Library (form-flow). It utilizes common, frequently-used libraries throughout, most of which are free and open source.
form-flowis included in the application'sbuild.gradle, along with all other dependencies. A detailed explanation ofform-flowconcepts and underlying functionality can be found in the library's README- JobRunr is used in this application to manage background jobs (eg, scheduling of email notifications, submission of applications over https)
In addition, the following product capabilities are enabled using third-party services:
- Street address validation using Smarty
- Email notifications using Twilio Sendgrid
- Email address validation using Twilio SendGrid Real Time Email Validation
- User analytics and event tracking using Mixpanel
- Error analytics and tracing using Sentry
- Observability, logging, monitoring, alerting using Datadog
- First, ensure that you have git installed on your local machine. If desired, you can also install a Github desktop client or preferred git plugin for your IDE.
- Clone this repository into your local environment. From your command line:
git clone git@github.com:codeforamerica/il-gcc-form-flow.gitYou'll need to provide some environment variables to run this application locally.
- To do this, create a new
.envfile by copying thesample.envfile in the root directory of your project:
cp sample.env .env
- You can find the dev environment variables and configs in the
Shared-SNLAB-ILfolder in LastPass. Put those values into your.envfile. - If you use IntelliJ IDEA, download the EnvFile plugin and follow the setup instructions here to set up Run Configurations with EnvFile. (see more IDE setup instructions below)
The setup.sh script:
- uses Homebrew to install all the necessary dependencies (such as java, gradle, postgres, node)
- runs the
generate_localhost_cert.shscript, which installs dependencies to create an SSL certification so you can usehttpswithlocalhostduring development - creates the main app database and users needed to run the application locally
- creates the database needed for running tests, and then runs the tests
To run from the command line, go to the root of the repository and run the setup.sh script:
./scripts/setup.sh
Or, run from within IntelliJ by clicking on the setup.sh file in the scripts directory and select Run 'setup.sh'.
- Install Java Temurin v 21
- Set 21 as your Java version in JAVA_HOME - see docs
- Install Gradle v8.11 or higher
- Install Postgres v14 or higher
- Install Libreoffice
- Make sure postgres is running
- Run the sql commands from the setup.sh script
./gradlew clean test
./generate_localhost_cert.sh
- If you need to set up the IntelliJ IDE, start by following the instructions from the form flow library here.
- In IntelliJ, run the application using the
IlGCCApplicationconfiguration (found inorg.ilgcc.app). The run will fail, but it will create a new run configuration in IntelliJ. - Open this new run configuration and configure it to use the
.envfile you created earlier with the EnvFile plugin:- Run -> Edit Configurations -> IlGCCApplication.
- Select
Enable EnvFileand manually add the.envfile you created using the+button.
- In your
.envfile, make sure theSPRING_PROFILES_ACTIVEis set todev - Run the application again. The application should start up successfully.
The following steps will allow you to seed your local db with the necessary counties, providers, and resource organizations:
- Import zip code <> county mapping data
- Import resource organization data
- Import provider data
Live Reload is very helpful when making changes to HTML templates, CSS, or JavaScript. Here are instructions on how to get IntelliJ to reload resources and have the LiveReload browser extension automatically reload the browser tab for you.
- Download live reload extension in your browser of choice:
- Restart your browser after install
- In IntelliJ, go to Edit configuration -> Modify options * On Frame deactivation: * Check - Update classes and resources
- Run your application from IntelliJ
- In your browser, go to
http://localhost:8080/ - Check that the live reload extension is "turned on", it will either be a solid color or a filled dot in the middle of the icon
- Now when you move focus away from IntelliJ, it will trigger an update and will then trigger a browser refresh
📹 Here's a video going step by step through these instructions.
This application includes the following types of automated tests:
- Unit tests (Junit)
- Integration / journey tests (Selenium)
- Accessibility tests: selenium tests using axe-core library to test against WCAG 2.1 rules as well as Deque accessibility best practices
To compile and run all tests:
./gradlew clean test
To run accessibility tests:
./gradlew accessibilityTest
To run a single journey test:
./gradlew test --tests org.ilgcc.app.journeys.GccFlowJourneyTest.fullGccFlow
In the scripts directory, you can find the following useful scripts:
(see above)
(see above)
This script will generate an empty migration file and place it in
the following directory: src/main/resources/db/migration. If you'd like
to change this location, you can edit the generate_migration.sh file
and update the migrations_paths variable.
The script will create the migration directory if it does not already exist.
It will prompt you to enter a short description of what the migration will do. It will then generate the file, with a name based on that description. The script will then open up the migration file in IntelliJ for you.
To run the script, simply type:
./generate_migration.shNote: if it does not run on the command line, you may need to give the script executable permission first, by running chmod u+x generate_migration.sh
Sometimes an IntelliJ update will cause the ILGCCApplication run context to fail. Here are some
ways to attempt to fix it.
- Invalidate the cache
- File -> Invalidate Caches...
- This will invalidate the caches and restart IntelliJ.
- Afterward, try to run the application. If this issue isn't fixed, try suggestion 2.
- Remove
.idea/modules- In the root of the repository, look for
.idea/modules - Make a copy of this folder and save somewhere else
- Delete this folder and all of its contents
- Quit IntelliJ
- Open IntelliJ, rebuild the project, hopefully modules are re-created from the application context
- In the root of the repository, look for
- If both of the above fail
- Make a copy of the entire
.ideafolder and save somewhere else. - Delete the original
.ideafolder - Quit IntelliJ
- Open IntelliJ, rebuild the project, hopefully modules are re-created from the application context and found
- Make a copy of the entire
If you have created live templates with fragments which are specific to your application based on a starter app template, you can commit them to your repository. You will follow a similar pattern to create templates to what is outlined in the form-flow library here.
An example template which was set up using this process, starting from an html snippet is available in this repository's IntelliJ settings folder.
To use a local version of the form-flow, library you can do the following:
- Clone the
form-flowrepo in the same directory as the starter app. - Build the
form-flowlibrary jar. - In this starter app, set the
SPRING_PROFILES_ACTIVEtodevin the.envfile. - Start the
form-flow-starter-app.
Changing the SPRING_PROFILES_ACTIVE to dev will cause the starter
app's build.gradle to pull in the local library, via this line:
implementation fileTree(dir: "$rootDir/../form-flow/lib/build/libs", include: '*.jar')
The Actuator is a feature Spring Boot provides to monitor and interact with your application. It opens endpoints that can be queried to get information about your application, like health and build information.
This app, by default, enables full access to all actuator endpoints in the dev profile for local development. However, in other profiles, it restricts access, allowing only the health and build information endpoints to be available for use outside of local development.
**
Please read the following section in Form Flow Library's documentation as well as Spring Boot's documentation. It's extremely important that you understand the actuator and what it provides and the risks, so that you can configure the feature accordingly.
To run set up this application to run exclusively on AWS, please see https://github.com/codeforamerica/il-gcc-infra
For Aptible configuration information, please see their documentation.
The Aptible CLI documentation is particularly helpful.
Here are the general steps to setup a new application in Aptible:
- Create a new environment and application in Aptible, or create a new application in an existing environment.
- Setup Aptible permissions to enable deploying your application, if they do not already exist.
- Provision a database for your application in Aptible.
- Add repository secrets for the deploy github action.
- Provision a new AWS S3 bucket.
- We use two buckets: one for non-production purposes and another for production.
- Replace the bucket names with your newly created buckets in the main application configuration and the demo application configuration.
These instructions guide you through the process of creating resources in Aptible + AWS which will allow you to deploy your application to a custom domain with root domain forwarding. Please create the resources in the specified order, as there are dependencies:
- Create a new hosted zone with the name corresponding to the root domain of your purchased domain name.
- Create a new managed HTTPS endpoint for your root domain with subdomain (i.e. www)
- In Aptible, be sure to include the following variable in your application's configuration environment:
FORCE_SSL=true. - Follow the instructions to create managed HTTPS validation records in Route53
- Request certificate in AWS Certificate Manager (ACM) for your purchased domain name. If you would like to support directing non-www to www traffic, please use your root domain for the fully qualified domain name in the request.
- Create records in AWS Route53
- Create a new S3 bucket with your root domain.
- Under the bucket properties, configure static website hosting with hosting type
of
Redirect requests for an object. Select Protocol ofnone.
- Create a new CloudFront distribution with CNAME corresponding to your root domain
- Associate the certificate that you created for your root domain. All other settings can remain as defaults.
- Create a Route53 Alias record for the root domain which points to your cloudfront distribution.