Spring-Boot-Angular-Template

Starter Template to create a OAuth2 secured dockerized Spring Boot 2.1 Application with Angular 8 Frontend.

A user with a Google- or Github-Account get access to the Application using OAuth2-Authentication, so no additional User Registration is required. A new user get the Default-Role ROLE_USER. Additional Roles, like ROLE_ADMIN for administrative access, can be assigned to a user through the Role-Management. The data get stored in a PostgreSQL database inside a Docker-Container.

Technology-Stack

Need to be installed on the OS to startup the application: Docker

Need to be installed on the OS for development purposes: Git, JDK 11, Maven, Lombok, Node.js, Angular-CLI

Getting Started

To get the application running, some configuration need to be to do.

Prerequisites

Step 1: Install Docker on your OS. Direct Download Links: Docker for Windows, Docker for Mac-OS

Step 2: After Docker is installed, go to the Docker-Settings and share the drive in which you will later download the latest Release of the Spring-Boot-Angular-Template. This is necessary for accessing the SQL-Files for setting up the database.

Obtaining API-Keys

To use the O2Auth-Authentication from Google or Github, we need to register this application to obtain the appropiate Client-ID and Client-Secret.

Step 1: Visit the Google Cloud Console

Step 2: Click on the Button Create Project

Step 3: In the following New Project-Dialog set as Project name spring_boot_angular_template and click on the Button Create

Step 4: On the top left, click on the Button with the three horizontal stripes to open the left-side Navigation-Menu. Select APIs & Services → Credentials

Step 5: In the Credentials-View click on the Button Create credentials and than select the Menu-Item OAuth client ID.

Step 6: In the Create OAuth client ID-Dialog type in following:

Click than on the Create-Button.

Step 7: A dialog appears with a generated client ID and client secret which you need to copy for later usage.

Step 1: Visit the Github Account Settings

Step 2: Press on the left navigation side menu the Menu-Item Developer-Settings

Step 3: In the Developer-Settings, select on the left navigation side menu OAuth Apps and click on the Button Register a new application.

Step 4: In the Register a new OAuth application-Dialog type in following:

Click than on the button Register application

Step 5: In the following view copy the generated Client ID and Client Secret for later usage.

ℹ️	Unfortunately github is not allowing adding more than one Homepage URL and Authorization callback URL. So for development purposes using the Google-OAuth2 should be prefered.

Installing

Step 1: Download the latest Release to your working-directory and unzip the file with following commands:

$ wget https://github.com/mrrobworks/spring-boot-angular-template/releases/download/v0.1-alpha/spring-boot-angular-template.tar.gz
$ tar -xvzf spring-boot-angular-template.tar.gz

Step 2: Load the Docker-Image to your Local Docker Registry with:

$ docker load < docker-image.tar

Step 3: In the file docker-compose.ref.yml search for the following entries:

GOOGLE_CLIENT_ID: [google-client-id]
GOOGLE_CLIENT_SECRET: [google-client-secret]
GITHUB_CLIENT_ID: [github-client-id]
GITHUB_CLIENT_SECRET: [github-client-secret]

Replace [google-client-id], [google-client-secret], [github-client-id], [github-client-secret] with your copied values from the Obtaining API-Keys-Section.

Run the application

Now you can simply run the application with following steps:

Step 1: Type following:

$ docker-compose -f docker-compose.yml -f docker-compose.ref.yml up

Step 2: In your Webbrowser type http://localhost:8091 and the webapplication shows up.

Development

Before development getting started, we need a terminal for executing commands. If you are running a bash-shell on a Linux-Distrubtion or Mac-OS everything should be fine. The Windows Powershell and CMD could make some problems and the build-process fails. My recommendation is to install the Windows Subsystem for Linux (WSL) in Windows 10 and using the bash-shell from it. For further use of Docker in WSL follow the instructions described in this Blog-Post.

Now we need to install some additional software:

Step 1: Install Git, JDK 11, Maven and Node.js on your OS.

Step 2: Open a terminal and type

$ npm install -g @angular/cli

to install the Angular-CLI

Step 3: Open your IDE and install Lombok as a Plugin.

Now we can download and install the Spring-Boot-Angular-Template for development:

Step 1: Git-Clone the Spring-Boot-Angular-Template to your working directory with:

$ git clone https://github.com/mrrobworks/spring-boot-angular-template.git
$ cd spring-boot-angular-template

Step 2: In the application.dev.yml you will find following:

google:
  client:
    client-id: [google-client-id]
    client-secret: [google-client-secret]
github:
  client:
    client-id: [github-client-id]
    client-secret: [google-client-secret]

Replace [google-client-id], [google-client-secret], [github-client-id], [github-client-secret] with your copied values from the Obtaining API-Keys-Section.

Step 3: Install the application with the command:

$ ./mvnw clean install

To start the PostgreSQL database in a Docker-Container, open a terminal, change the location to the project-root directory and type following:

$  docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

If you develop with IntelliJ IDEA there are also some Run-Configurations in the Project-Repository. Start the Run-Configurations docker-compose-DEV, backend-spring-boot-DEV and frontend-angular-DEV in IntellJ and you are ready to go. Open a webbrowser, type http://localhost:4200 and the webapplication shows up.

Troubleshooting

Trouble 1: When installing the application with ./mvnw clean install and you getting a error like this:

[ERROR] Get https://registry-1.docker.io/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)
[WARNING] An attempt failed, will retry 1 more times
org.apache.maven.plugin.MojoExecutionException: Could not build image

then restart the Docker deamon and the error should be gone.

Trouble 2: Using CMD or Powershell in Windows and install the application with mvnw.cmd clean install it appears following:

[INFO] > cd bin && ng build --prod
[INFO]
[ERROR] 'ng' is not recognized as an internal or external command,
[ERROR] operable program or batch file.

This is usually a problem when installing the application with CMD or Powershell. The command ng from the Angular-CLI is not recognized correctly. You need to install Node.js and Angular-CLI and then set the corresponding Windows-Evironment-Path variables. Also you can change in frontend/package.json the following:

"scripts": {
    "ng": "ng",
    "start": "ng serve --proxy-config proxy.conf.json",
    "build": "ng build --prod",
    "test": "ng test",
    "lint": "ng lint",
    "e2e": "ng e2e"
  }

Trouble 3: Resolving EACCES permissions errors when installing packages globally

[INFO] Running 'npm install -g @angular/cli@8.0.0' in /mnt/c/opt/workspace/intellij/spring-boot-angular-template/frontend
[ERROR] npm ERR! path /mnt/c/opt/workspace/intellij/spring-boot-angular-template/frontend/lib/node_modules/@angular/cli/node_modules/normalize-package-data[ERROR] npm ERR! code EACCES[ERROR] npm ERR! errno -13
[ERROR] npm ERR! syscall rename[ERROR] npm ERR! Error: EACCES: permission denied, rename '/mnt/c/opt/workspace/intellij/spring-boot-angular-template/frontend/lib/node_modules/@angular/cli/node_modules/normalize-package-data' -> '/mnt/c/opt/workspace/intellij/spring-boot-angular-template/frontend/lib/node_modules/@angular/cli/node_modules/.normalize-package-data.DELETE'

Follow the instructions from here.

TODOs

❏ Redesign Angular-Frontend CSS
❏ Replace some components in frontend (Checkbox)
❏ Review Code in Frontend
❏ WebMvcTest for REST-Controller (mockMvc)
❏ Add Swagger Documentation for REST-Controllers
❏ Swagger with OAuth2 or BasicAuth?
❏ Add spring-boot-devtools?
❏ Using EntityGraph for JPA (instead FetchType.EAGER)?
✓ Fix .gitignore-File
✓ Add Mockito Tests
✓ Create ViewModel-Beans for each JPA-Model-Entity-Bean? Using Mapstruct.
✓ Using var for local-variables
✓ Microservices from this project for creating github-repositories
✓ Remove Maven-Module dbsetup and move sql-Files to backend
✓ Replace Liquibase with Flyway
✓ Changing return types of REST-Controllers to ResponseEntity
✓ User-Roles Access on custom sites / elements
✓ Angular / CSS / Bootstrap (Angular-Material implemented)
✓ Profile in OAuthSecurityConfiguration (Google, Github)
✓ User-Role-assignment through webapplication
✓ Save LoggedIn User to Session
✓ CRUD Roles for Administrator of the Application
✓ Building Docker-Image with Spring-Boot and Angular
✓ Create schema.sql and data.sql for script based data initialization
✓ Validation Rules in backend-model classes (Java Bean Validation API, JSR-303)
✓ application.properties change to application.yml
✓ Update README.md with actual installation instructions for development and how to setup Intellij / Docker.
✓ application-external.properties to yml and add installation instructions to README.md
✓ Login-Site Radio-Button Google and Github link to /login and /login/github

mrrobworks / spring-boot-angular-template