Skip to content

Latest commit

 

History

History
151 lines (103 loc) · 5.39 KB

README.md

File metadata and controls

151 lines (103 loc) · 5.39 KB
Raw

STARTER-team03

TODO: Adjust the link to the deployed production app 
for your team here, then remove this TODO.

TODO: Adjust the link to the deployed qa app 
for your team here, then remove this TODO.

Environment needed

The code in this repo requires:

  • Version v16.20.0 of node (precisely)
    • To install this version of node, you can use nvm (Node Version Manager)
    • The commands needed are: 
      nvm install 16.20.0  # one time step
nvm use 16.20.0      # every time you start a new shell
  • Version 17 of Java
    • Any version 17.x.y will do; there are no known requirements for a specific version, so using the latest 17.x.y version is suggested.

See also: docs/versions.md, which describes the places in the code base that need to change if/when the version of Java or node needs to be updated.

Configuring GitHub Pages for the documentation

This repo contains Github Actions scripts that automatically create and publish documentation for the code:

  • javadoc for the backend Java code
  • Storybook for the frontend React code

To set this up, follow the instructions here: docs/github-pages.md

Getting Started on localhost

Before running the application for the first time on localhost, you must:

Otherwise, when you try to login for the first time, you will likely see an error such as:

Authorization Error; Error 401: invalid_client; The OAuth client was not found.

Then:

  • Open two separate terminal windows
  • In the first window, start up the backend with: 
    mvn spring-boot:run
  • In the second window: 
    cd frontend
npm install  # only on first run or when dependencies change
npm start

The app should then be available on http://localhost:8080

Note: http://localhost:8080 not http://localhost:3000

The npm start command may open up a web browser with the app running on port http://localhost:3000.

  • You should close this window and work in one where you put in the url http://localhost:8080.

  • The http://localhost:3000 window has a frontend that is not connected to the backend and most functions in that window will fail to work.

  • If you want to avoid this useless browser window opening up,
    instead of npm start, type this:

    BROWSER=none npm start

What if it doesn't work?

If it doesn't work at first, e.g. you have a blank page on http://localhost:8080, give it a minute and a few page refreshes. Sometimes it takes a moment for everything to settle in.

If you see the following on localhost, make sure that you also have the frontend code running in a separate window.

Failed to connect to the frontend server... 

On Dokku, be sure that PRODUCTION is defined. 

On localhost, open a second terminal window, 
cd into frontend and type: npm install; npm start";

Getting Started on Dokku

Accessing swagger

Swagger is a tool that allows you to work directly with the RESTful API endpoints of the backend. It is similar to the tool Postman, but more convenient because it is built directly into the application.

To access the Swagger API endpoints, use:

You can also append /swagger-ui/index.html to the URL manually when running on Dokku.

To run React Storybook locally (for development)

  • cd into frontend
  • use: npm run storybook
  • This should put the storybook on http://localhost:6006
  • Additional stories are added under frontend/src/stories

You can also see the storybook for the main branch and all open pull requests on the github pages site associated with the repo; see /docs/github-pages.md for more info.

To generate javadoc (locally, for development)

  • cd to top level of repo
  • use: mvn javadoc:javadoc
  • open in a web browser: target/site/apidocs/index.html

You can also see the javadoc for the main branch and all open pull requests on the github pages site associated with the repo; see docs/github-pages.md for more info.

SQL Database access

On localhost:

  • The SQL database is an H2 database and the data is stored in a file under target
  • Each time you do mvn clean the database is completely rebuilt from scratch
  • You can access the database console via a special route, http://localhost:8080/h2-console
  • For more info, see docs/h2-database.md

On Dokku:

  • The SQL database is a postgres database provisioned automatically by Dokku
  • More info and instructions for accessing the SQL prompt are at docs/postgres-database.md