mrrobworks/spring-boot-angular-template

:icons: font

ifdef::env-github[]
:tip-caption: 💡
:note-caption: ℹ️
:important-caption: ❗
:caution-caption: 🔥
:warning-caption: ⚠️
endif::[]

= 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.

.Login-Screen
image:https://user-images.githubusercontent.com/37511144/57142263-678bb880-6dbc-11e9-924d-14ab1ed2c710.png[spring-boot-angular-login]

== Technology-Stack image:http://img.shields.io/badge/tech-stack-0690fa.svg?style=flat["StackShare", link="https://stackshare.io/mrrobworks/spring-boot-angular-template-stack"]

image:https://user-images.githubusercontent.com/37511144/66196552-092f7280-e699-11e9-9c04-3c1e65f146d3.png[spring-boot-angular-template-stack]

Need to be installed on the OS to startup the application:
https://www.docker.com/get-started[Docker]

Need to be installed on the OS for development purposes: https://git-scm.com/downloads[Git],
https://www.oracle.com/technetwork/java/javase/downloads/jdk11-downloads-5066655.html[JDK 11],
https://maven.apache.org/download.cgi[Maven],
https://projectlombok.org/download[Lombok],
https://nodejs.org/en/[Node.js],
https://cli.angular.io/[Angular-CLI]

== Getting Started

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

=== Prerequisites

Step 1: Install https://www.docker.com/get-started[Docker] on your OS. Direct Download Links:
https://download.docker.com/win/stable/Docker%20for%20Windows%20Installer.exe[Docker for Windows],
https://download.docker.com/mac/stable/Docker.dmg[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
https://github.com/mrrobworks/spring-boot-angular-template/releases/download/v0.1-alpha/spring-boot-angular-template.tar.gz[latest Release]
of the Spring-Boot-Angular-Template.
This is necessary for accessing the SQL-Files for setting up the database.

[[obtaining-api-keys]]
=== 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.

'''

image:https://user-images.githubusercontent.com/37511144/55681624-ab5be100-5928-11e9-82bf-e5e352485c17.png[google,width=250]

Step 1: Visit the https://cloud.google.com/console/project[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:

image:https://user-images.githubusercontent.com/37511144/55275019-eb471680-52df-11e9-85c3-a7e549762505.png[create oauth client id]

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.

'''

image:https://user-images.githubusercontent.com/37511144/55681693-96cc1880-5929-11e9-980e-986a753386ae.png[github,width=250]

Step 1: Visit the https://github.com/settings/profile[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:

image:https://user-images.githubusercontent.com/37511144/56457063-baee1780-6375-11e9-8c7a-50a4470a8c9b.png[github-register-new-oauth-application]

Click than on the button Register application

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

NOTE: 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 https://github.com/mrrobworks/spring-boot-angular-template/releases/download/v0.1-alpha/spring-boot-angular-template.tar.gz[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 <>-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
https://docs.microsoft.com/de-de/windows/wsl/install-win10[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
https://nickjanetakis.com/blog/setting-up-docker-for-windows-and-wsl-to-work-flawlessly[Blog-Post].

Now we need to install some additional software:

Step 1: Install https://git-scm.com/downloads[Git],
https://www.oracle.com/technetwork/java/javase/downloads/jdk11-downloads-5066655.html[JDK 11],
https://maven.apache.org/download.cgi[Maven] and https://nodejs.org/en/[Node.js] on your OS.

Step 2: Open a terminal and type

$ npm install -g @angular/cli

to install the https://cli.angular.io/[Angular-CLI]

Step 3: Open your IDE and install https://projectlombok.org/download[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 <>-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 https://www.jetbrains.com/idea/[IntelliJ IDEA] there are also some
https://github.com/mrrobworks/spring-boot-angular-template/tree/master/.idea/runConfigurations[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 https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally[here].

== TODOs

mrrobworks/spring-boot-angular-template

Languages

Contributors

Latest Release