• Introduction
• Repository structure
• Prerequisites
  • Tools
  • Configure .env file
  • Verify run configurations and makefile targets
  • Frontend dependencies
  • Backend dependencies
• Run the app locally
  • Profile "local-ide" - default & preferred
    • Run the frontend
    • Run the backend
    • Access the app via the browser
  • Profile "local-ide-embedded"
    • Build the frontend
    • Run the backend
    • Access the app via the browser
  • Profile "local-docker"
    • Build the Docker image
    • Run the Docker image
    • Access the app via the browser
• Run the unit tests
  • Run the frontend tests
  • Run the backend tests
• Run the e2e tests
  • Prerequisites
  • Profile "local-ide"
  • Profile "local-ide-embedded"
  • Profile "local-docker"
  • Profile "prod"
• Update the README
• Wiki and other documentation resources

This repository is a fork of the popular kata named Trivia. It first started as a regular solution of the kata, then turned into a web application built on top of it.

Why ? Just because ! It was seen as a fun exercise to brush the rust off after months of relative inactivity, and a reason to get my hand on Angular and other tools or techniques.

.
├── *                           ignore any files and directory other than "java" or ".github"
├── .github                        
│   └── workflows
│      └── pipeline.yml         the Github Actions pipeline
└── java                        
    ├── pom.xml                 root pom, as the project is setup as a multi-module Maven project
    ├── backend                 backend of the app, defined as a Maven module
    ├── e2e-tests               e2e tests using Playwright-java, defined as a Maven module
    ├── frontend-angular        the frontend, using Angular 
    ├── infra                   Terraform scripts to setup the envs (empty for the moment) 
    ├── docs                    miscellaneous drawio files to support design, and screenshots used in the README
    ├── .run                    run configurations to run the backend and e2e tests
    ├── pipeline.Dockerfile     Dockerfile used in the pipeline
    ├── Makefile                targets to execute most if not all actions necessary for development and some more
    └── openapi.yaml            Golden Source API contract exposed by the backend, used by the frontend.

• IntelliJ
• java 21 (optional if using IJ provided JVM)
• node & npm - Using nvm for example
• Angular CLI v17 - Installation guide
• openapi-generator-cli - Installation guide
• make (optional if you are not interested in executing actions using Makefile targets)

Used to reference variables by both run configurations and Makefile targets. Also used to store secrets for e2e test user.

Copy template.env to .env. Ask for the secrets and replace them in .env.

Most actions described in the README should an IntelliJ run configuration, saved in .run directory and versioned in git. They should be preconfigured in your IDE.

Most actions should also have an associated Makefile target

Both rely on a properly configured .env file

• node & npm - Using nvm for example
• Angular CLI v17 - Installation guide
• openapi-generator-cli - Installation guide
• Generate the openapi stubs with the Makefile target generate-frontend-stubs-from-openapi
• Generate the environment files with the Makefile target generate-frontend-environment-files

• java 21
• maven is not necessary as maven wrapper is used in Makefile targets

There are several ways to run the application locally, we will refer them as "profiles"

The most standard way used in day to day development. Although the name refers to "IDE", you can actually run the frontend, the backend or both in this profile using the CLI.

The frontend runs on port 4200 and the backend on port 8080

You can run the frontend using an IJ run configuration run-frontend - local-ide

Or using the terminal

cd java/frontend-angular
ng serve

The frontend should start without issue and the output should look like the following:

Select the run configuration backend - local-ide:

You should get an output as follows (here backend started in debug)

You can now access the app via the browser. Go to localhost:4200:

Choose an authentication method and have fun with the app.

The frontend is hosted by the backend. The frontend build artifacts are placed in src/main/resources/static of the backend.

The option watch is set to true so that there is live reload on the frontend AND the backend.

The goal of this profile is to have a setup similar to what will be deployed, but with fast feedback loops.

it is useful for example to verify Angular routes and Spring MVC routes do not step on each other's toes.

The application is accessed via port 8100

Using the Makefile target build-frontend-local-ide-embedded

Or the IntelliJ run config build-frontend - local-ide-embedde

Using the Makefile target run-backend-local-ide-embedded or debug-backend-local-ide-embedded

You can now access the app via the browser. Go to localhost:8100:

Similar to local-ide-embedded, but not ran through the IDE, and packaged into a docker image, ran locally. It's useful to verify for some specific configs and setups, for example the spring config location, other local resources paths, or the Dockerfile.

No live reload on this one

Using the Makefile target build-docker-local

Using the Makefile target run-docker-local

You can now access the app via the browser. Go to localhost:8110:

Use the pre-registered run configuration test frontend

Or use the Makefile target unittests-frontend

everything should be green, you should obtain an output as following:

Use the pre-registered run configuration ng test

You should get an output as follows:

Or use the Makefile target unittests-backend

The goal of these tests is to ensure beyond any doubt that the application does work. They run against a running instance of the app, whether locally or in an environment.

The way the app is configured to run called is called "profile". cf section Run the app locally for more info.

1. Create a test user and rename it "qa-user"
2. (Re)define the values QA_USER_ID, QA_USER_EMAIL, QA_USER_PASSWORD, FIREBASE_API_KEY in the .env file
3. (Re)define the value HOSTNAME_PROD to run tests against the prod environment if configured

the backend and the frontend are ran locally from the IDE or the CLI.

cf section run the app locally - profile "local-ide" for instructions on how to run the app in that configuration

Select the run config e2e-tests - local-ide to run all tests.

You can also select a run config related to e2e tests targeting a specific "feature", in our case mapping to a page, of the application.

At the moment, e2e tests are configured to use Chrome. A browser should open and run the tests. After around 2 minutes, the tests should end and everything should be green.

Or run the Makefile target e2e-tests-local-ide

the frontend is hosted by the backend.

cf section run the app locally - profile "local-ide-embedded" for more details and instructions to run this configuration.

Select the run config e2e-tests - local-ide-embedded to run all tests.

Just like for the local-ide profile, there are run configurations available for specific features / pages.

Or run the Makefile target e2e-tests-local-ide-embedded

Just like the configuration "local-ide-embedded", but packaged in a Docker image

cf section run the app locally - profile "local-docker" for more details and instructions to run this configuration.

Just like for the other profiles described above, there are run configurations available for specific features / pages.

Or run the Makefile target e2e-tests-local-docker

After setting up the prod environment, the cicd pipeline and everything else necessary to deploy the application in production (README section coming soon)

README.md is generated so don't update it directly. Update README.template.md, then run the Makefile target generate-readme

https://github.com/mbimbij/trivia/wiki