Readme updates (#1063)

* default DB settings for the more common way to run TI

* add local DB info, clarify a few things

---------

Co-authored-by: jcrichlake <[email protected]>

README.md

@@ -10,11 +10,13 @@ To run the application directly, execute...
 ./gradlew clean run
 ```
 
-This will run the web API on port 8080.  You can view the API documentation at `/openapi`.
+This runs the web API on port 8080. The app reads/writes data to a local file (unless you have a DB configured)
+
+You can view the API documentation at `/openapi`.
 
 ### Generating and using a token
 1. Run `brew install mike-engel/jwt-cli/jwt-cli`
-2. Run `jwt encode --exp='+5min' --jti $(uuidgen) --alg RS256  --no-iat -S @/PATH_TO_FILE_ON_YOUR_MACHINE/trusted-intermediary/mock_credentials/organization-trusted-intermediary-private-key-local.pem`
+2. Replace `PATH_TO_FILE_ON_YOUR_MACHINE` in this command with the actual path, then run it: `jwt encode --exp='+5min' --jti $(uuidgen) --alg RS256  --no-iat -S @/PATH_TO_FILE_ON_YOUR_MACHINE/trusted-intermediary/mock_credentials/organization-trusted-intermediary-private-key-local.pem`
 3. Copy token from terminal and paste into your postman body with the key `client_assertion`
 4. Add a key to the body with the key `scope` and value of `trusted-intermediary`
 5. Body type should be `x-wwww-form-urlencoded`
@@ -32,18 +34,30 @@ The additional requirements needed to contribute towards development are...
 - [Python](https://docs.python-guide.org/starting/installation/)
 - [Terraform](https://www.terraform.io)
 - [Liquibase](https://www.liquibase.com/download)
+- [Docker](https://www.docker.com/)
 
 ### Generating .env File
 
-To set up the necessary environment variables, you can use the `generate_env.sh` script. This script will create a `.env` file in the resource folder with the required configuration. Follow these steps:
+To set up the necessary environment variables, run the `generate_env.sh` script. This script
+creates a `.env` file in the resource folder with the required configuration
 
 1. Navigate to the project directory.
-
 2. Run the `generate_env.sh` script:
 
    ```bash
    ./generate_env.sh
    ```
+3. If you run TI using Docker rather than Gradle, update the DB and port values in the `.env` file (the alternate values are in comments)
+
+### Using a local database
+Use [docker-compose.postgres.yml](docker-compose.postgres.yml) to run your local DB. In IntelliJ, you can click the play arrow to start it
+
+![docker-postgres.png](images/docker-postgres.png)
+
+Apply all outstanding migrations:
+```bash
+liquibase update --changelog-file ./etor/databaseMigrations/root.yml --url jdbc:postgresql://localhost:5433/intermediary --username intermediary --password 'changeIT!' --label-filter '!azure'
+```
 
 ### Compiling
 
@@ -68,6 +82,8 @@ To run the unit tests, execute...
 #### End-to-end Tests
 
 End-to-end tests are meant to interact and assert the overall flow of the API is operating correctly. They require that the API to be running already.
+The end-to-end tests use whatever database configuration is already in place - if you're using the local filesystem,
+so will the e2e tests (this is how they work on github), and if you're using a DB, so will the tests
 
 To run them, execute...
 

generate_env.sh

@@ -9,8 +9,8 @@ KEY_VAULT-NAME=ti-key-vault-name
 REPORT_STREAM_URL_PREFIX=http://localhost:7071
 STORAGE_ACCOUNT_BLOB_ENDPOINT=https://cdctiinternal.blob.core.windows.net
 METADATA_CONTAINER_NAME=metadata
-DB_URL=postgresql # for gradlew: DB_URL=localhost
-DB_PORT=5432      # for gradlew: DB_PORT=5433
+DB_URL=localhost  # if you run TI via docker: DB_URL=postgresql
+DB_PORT=5433      # if you run TI via docker: DB_PORT=5432
 DB_NAME=intermediary
 DB_USER=intermediary
 DB_PASS=changeIT!