Running outside of docker

Run on IntelliJ

This setup is highly recommended. Most of the team runs directly using IntelliJ. Refer to IntelliJ run configurations to set up IntelliJ to run the app.

We include IntelliJ configurations in our project, so they should appear automatically once you're up and running on IntelliJ.

To start the application:

1. Run the db up configuration
2. Run the Backend configuration
3. Run the Frontend configuration

To start the application using Okta (required if you're testing any authentication or user management changes)

1. Run the db up configuration
2. Run the Backend Okta config. You'll need to update the OKTA_API_KEY in the backend run configuration with a real key. Reach out to one of the other developers for the secret, or generate your own token.
3. Run the Frontend with Okta config. The environment variables there are: REACT_APP_OKTA_ENABLED=true;REACT_APP_OKTA_URL=https://hhs-prime.oktapreview.com;REACT_APP_OKTA_CLIENT_ID={$CLIENT_ID};REACT_APP_OKTA_SCOPE=simple_report_dev

Note that if you run the database outside Docker, you don't need to run the db up configuration. See [Setup] Running DB outside of Docker (optional).

You may still need to install some dependencies, depending on your local machine. For those instructions, keep reading.

Running outside Docker

Running outside of Docker is encouraged for developers working on feature work.

There are three major components to the application:

• a PostgreSQL database
  • can be run locally or via Docker
• a Java SpringBoot backend
• a React frontend

Setup

Install Dependencies

To run locally, you need a JDK, Node, and some way of running PostgreSQL.

Java

To install Java on a Mac:

brew tap adoptopenjdk/openjdk
brew install --cask adoptopenjdk17
brew install gradle

To install Java on Linux, install with jabba, the Java version manager:

curl -sL https://github.com/shyiko/jabba/raw/master/install.sh | bash && . ~/.jabba/jabba.sh
jabba install [email protected]
jabba use [email protected]

Note you can also install with jabba on Mac.

Node

Install Node. Version 18 is required for yarn to build packages correctly

• You may wish to use a node version manager such as nvm

You'll need yarn as well for package management. If you don't have it installed, run brew install yarn.

Database

Most of us use Docker, but you can also run it as a service separately. See [Setup] Running DB outside of Docker (optional).

1. Install Docker and docker-compose (if you plan to run the database in Docker)
   • You can install docker hub directly from the docker hub website. This is the preferred solution and should come with docker-compose
   • Alternatively, you can install Docker and run it as a daemon: brew install docker docker-compose.

Local Settings

Backend

To edit Spring Boot settings for your local set up, you must first create an application-local.yaml (note this file is git ignored):

1. Create the application-local.yaml file in the repo's backend/src/main/resources directory

touch backend/src/main/resources/application-local.yaml

Example application-local.yml file:

logging:
  pattern:
    console: "%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){faint} %clr(%5p) %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} [Query: %X{graphql-query}] %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n%wEx"
spring:
  datasource:
    simplereport:
      hikari:
        jdbc-url: jdbc:postgresql://localhost:5432/simple_report
    metabase:
      hikari:
        jdbc-url: jdbc:postgresql://localhost:5432/metabase
  jpa:
    properties:
      hibernate:
        show_sql: true
        format_sql: true # override this in application-local.yaml to get pretty-printed SQL all the time
        default_schema: simple_report
  liquibase:
    simplereport:
      user: simple_report_migrations
      password: migrations456
      default-schema: simple_report
    metabase:
      user: simple_report_migrations
      password: migrations456
      default-schema: public

Other useful settings:

• set CORS allowed-origins (this can be useful for testing the Okta integration)

simple-report:
  cors:
    allowed-origins:
      - http://localhost:3000

• setting smarty credentials for address validation. If this is not added, an error will occur when validating addresses

SMARTY_AUTH_ID: get_from_team
SMARTY_AUTH_TOKEN: get_from_team

• set default user roles (useful for running e2e tests locally but not necessary to run the app)

simple-report:
  demo-users:
    default-user:
      authorization:
        granted-roles: ADMIN
    site-admin-emails: [email protected]

Frontend

To edit React settings, create frontend/.env.local (git ignored). Note that this frontend setup is likely not needed at all, but you may wish to reference this as an example:

1. Create a .env.local file in the repo's frontend/src directory

touch frontend/src/.env.local

2. Copy and save the content below into that newly created file:

Running without Okta:

REACT_APP_DISABLE_MAINTENANCE_BANNER=true

Running with Okta:

REACT_APP_BACKEND_URL=http://localhost:8080
REACT_APP_BASE_URL=http://localhost:3000
REACT_APP_OKTA_ENABLED=true

Run outside IntelliJ

You can also run the app outside IntelliJ and Docker (for Docker instructions, see the README.) Options for running independently are below.

Running the backend

Running with Docker:

1. cd backend
2. Run docker-compose up --build
3. view site at http://localhost:8080

Running spring app locally and db in Docker

1. cd backend
2. Run docker-compose up -d db
3. Run ./gradlew bootRun --args='--spring.profiles.active=dev'
4. view site at http://localhost:8080

Running spring app locally and db in Docker on port 5433

1. cd backend
2. Run docker-compose --env-file .env.development up db
3. Run SR_DB_PORT=5433 ./gradlew bootRun --args='--spring.profiles.active=dev'
4. view site at http://localhost:8080

The GraphQL playground should load after replacing the default request url with http://localhost:8080/graphql

Running locally with Okta

You can run the app against the "Okta Preview" instance by running the backend with the okta-local, local Spring profiles. Be sure to set the OKTA_API_KEY environment variable. You can generate an API token for yourself by logging into the Okta Preview admin panel and going into Security > API > Tokens.

In addition to your local environment setup, you will need to do some additional setup in Okta for full access to the app locally. Follow the instructions on the Setting-up-okta page to set this up.