Running outside of docker - CDCgov/prime-simplereport GitHub Wiki
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:
- Run the
db up
configuration - Run the
Backend
configuration - Run the
Frontend
configuration
To start the application using Okta (required if you're testing any authentication or user management changes)
- Run the
db up
configuration - 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. - 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 adoptopenjdk11
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).
- 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):
- Create the
application-local.yaml
file in the repo'sbackend/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:
- Create a
.env.local
file in the repo'sfrontend/src
directory
touch frontend/src/.env.local
- 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:
cd backend
- Run
docker-compose up --build
- view site at http://localhost:8080
Running spring app locally and db in Docker
cd backend
- Run
docker-compose up -d db
- Run
./gradlew bootRun --args='--spring.profiles.active=dev'
- view site at http://localhost:8080
Running spring app locally and db in Docker on port 5433
cd backend
- Run
docker-compose --env-file .env.development up db
- Run
SR_DB_PORT=5433 ./gradlew bootRun --args='--spring.profiles.active=dev'
- 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.