Skip to content

Commit 8d19c40

Browse files
joneubankjoneubank
committed
README Updates - Quick Start and project README template
1 parent 6e8ddbc commit 8d19c40

File tree

4 files changed

+210
-3
lines changed

4 files changed

+210
-3
lines changed

‎.gitignore

+7-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
target/
22
!.mvn/wrapper/maven-wrapper.jar
3+
.env
4+
env
5+
env.sh
36

47
### STS ###
58
.apt_generated
@@ -21,4 +24,7 @@ build/
2124
nbbuild/
2225
dist/
2326
nbdist/
24-
.nb-gradle/
27+
.nb-gradle/
28+
29+
### VSCode ###
30+
.vscode

‎README.md

+109-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,109 @@
1-
# microservice-template-java
1+
# Java Microservice Quickstart Template
2+
Spring-Boot application preconfigured for to use [EGO](https://github.com/overture-stack/ego/) generated JWTs for authorization.
3+
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
4+
5+
6+
## Features
7+
This template provides the following:
8+
9+
* Spring-Boot Application with Spring Security
10+
* JWT Authentication
11+
* JWT Asymmetric Verificaiton - fetches public-key from web on start-up
12+
* JWT Filter - User Role and Status requirements implemented by default
13+
* Docker and Docker-Compose configuration
14+
15+
16+
## Requirements
17+
The following software is required to run the application. It can be run locally or in a docker container.
18+
19+
20+
### EGO
21+
A running instance of [EGO](https://github.com/overture-stack/ego/) is required to generate the Authorization tokens and to provide the verification key.
22+
23+
[EGO](https://github.com/overture-stack/ego/) can be cloned and run locally if no public server is available.
24+
25+
26+
### Local
27+
* [Java 8 SDK](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
28+
* [Maven](https://maven.apache.org/download.cgi)
29+
30+
31+
### Docker
32+
* [Docker](https://www.docker.com/get-docker)
33+
34+
35+
## Quick Start
36+
Make sure the JWT Verification Key is configured, then you can run the server in a docker container or on your local machine.
37+
38+
39+
### Configure JWT Verification Key
40+
Update __application.yml__. Set `auth.jwt.publicKeyUrl` to the URL to fetch the JWT verification key. The application will not start if it can't set the verification key for the JWTConverter.
41+
42+
The default value in the __application.yml__ file is set to connect to EGO running locally on its default port `8081`.
43+
44+
### Run Local
45+
```bash
46+
$ mvn spring-boot:run
47+
```
48+
49+
Application will run by default on port `1234`
50+
51+
Configure the port by changing `server.port` in __application.yml__
52+
53+
54+
### Run Docker
55+
56+
First build the image:
57+
```bash
58+
$ docker-compose build
59+
```
60+
61+
When ready, run it:
62+
```bash
63+
$ docker-compose up
64+
```
65+
66+
Application will run by default on port `1234`
67+
68+
Configure the port by changing `services.api.ports` in __docker-compose.yml__. Port 1234 was used by default so the value is easy to identify and change in the configuration file.
69+
70+
### Test Endpoint
71+
The application has a single endpoint `/test` that will accept GET and POST requests with a valid token.
72+
73+
A JWT must be passed in a request header, following the Bearer token pattern. Below is a usable value to test with, it is valid vs. the example keystore given in the EGO repo.
74+
75+
```
76+
Authorization=Bearer eyJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1MTI3NjIxODIsImV4cCI6MjE0NzQ4MzY0Nywic3ViIjoiNjA2IiwiaXNzIjoiZWdvIiwiYXVkIjpbXSwiY29udGV4dCI6eyJ1c2VyIjp7Im5hbWUiOiJEZW1vLlVzZXJAZXhhbXBsZS5jb20iLCJlbWFpbCI6IkRlbW8uVXNlckBleGFtcGxlLmNvbSIsInN0YXR1cyI6IkFwcHJvdmVkIiwiZmlyc3ROYW1lIjoiRGVtbyIsImxhc3ROYW1lIjoiVXNlciIsImNyZWF0ZWRBdCI6IjIwMTctMTEtMjIgMDM6MTA6NTUiLCJsYXN0TG9naW4iOiIyMDE3LTEyLTA4IDA3OjQzOjAyIiwicHJlZmVycmVkTGFuZ3VhZ2UiOm51bGwsInJvbGVzIjpbIlVTRVIiXX19LCJqdGkiOiI0OGE5NGIzNy1mMTJlLTQxNWQtYjM1Zi1kZDhmOThiMDQ4ZDcifQ.Cmgbd_xnUp8dPnIJvmUXmh5LYnHgHSk_n_0VzCn0k9r4WVNdsupb-MQqJvgOMg3K8si5mzhIjzLi9rZL5N_JwFXtpjKXKRVT7KF4mYfqF7bVNm6tkQg6CeAGhiuaMujhLhASS79LVBPKOv1tk79WuVu-VKHzyLS1h3yFQAsjLVQxA6_0MD7zKa1W3Nbhte6lHwgiNo1AlxuIJzP37-2saNb-aUy9DigmH3_C2oPqxpBu-YNnaekO5jNmbfucMinlpxCpEw-UvpvxI9Xk_9E73TNQE9acNQyyg_BxdnVbwDsR-kG5QXNrlEAxGm-1yY6w8Nvqxcp-3uoff6K0uKLUdQ
77+
```
78+
79+
Test cURL requests:
80+
```bash
81+
curl -X GET \
82+
http://localhost:1234/test \
83+
-H 'authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1MTI3NjIxODIsImV4cCI6MjE0NzQ4MzY0Nywic3ViIjoiNjA2IiwiaXNzIjoiZWdvIiwiYXVkIjpbXSwiY29udGV4dCI6eyJ1c2VyIjp7Im5hbWUiOiJEZW1vLlVzZXJAZXhhbXBsZS5jb20iLCJlbWFpbCI6IkRlbW8uVXNlckBleGFtcGxlLmNvbSIsInN0YXR1cyI6IkFwcHJvdmVkIiwiZmlyc3ROYW1lIjoiRGVtbyIsImxhc3ROYW1lIjoiVXNlciIsImNyZWF0ZWRBdCI6IjIwMTctMTEtMjIgMDM6MTA6NTUiLCJsYXN0TG9naW4iOiIyMDE3LTEyLTA4IDA3OjQzOjAyIiwicHJlZmVycmVkTGFuZ3VhZ2UiOm51bGwsInJvbGVzIjpbIlVTRVIiXX19LCJqdGkiOiI0OGE5NGIzNy1mMTJlLTQxNWQtYjM1Zi1kZDhmOThiMDQ4ZDcifQ.Cmgbd_xnUp8dPnIJvmUXmh5LYnHgHSk_n_0VzCn0k9r4WVNdsupb-MQqJvgOMg3K8si5mzhIjzLi9rZL5N_JwFXtpjKXKRVT7KF4mYfqF7bVNm6tkQg6CeAGhiuaMujhLhASS79LVBPKOv1tk79WuVu-VKHzyLS1h3yFQAsjLVQxA6_0MD7zKa1W3Nbhte6lHwgiNo1AlxuIJzP37-2saNb-aUy9DigmH3_C2oPqxpBu-YNnaekO5jNmbfucMinlpxCpEw-UvpvxI9Xk_9E73TNQE9acNQyyg_BxdnVbwDsR-kG5QXNrlEAxGm-1yY6w8Nvqxcp-3uoff6K0uKLUdQ'
84+
```
85+
86+
```bash
87+
curl -X POST \
88+
http://localhost:1234/test \
89+
-H 'authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1MTI3NjIxODIsImV4cCI6MjE0NzQ4MzY0Nywic3ViIjoiNjA2IiwiaXNzIjoiZWdvIiwiYXVkIjpbXSwiY29udGV4dCI6eyJ1c2VyIjp7Im5hbWUiOiJEZW1vLlVzZXJAZXhhbXBsZS5jb20iLCJlbWFpbCI6IkRlbW8uVXNlckBleGFtcGxlLmNvbSIsInN0YXR1cyI6IkFwcHJvdmVkIiwiZmlyc3ROYW1lIjoiRGVtbyIsImxhc3ROYW1lIjoiVXNlciIsImNyZWF0ZWRBdCI6IjIwMTctMTEtMjIgMDM6MTA6NTUiLCJsYXN0TG9naW4iOiIyMDE3LTEyLTA4IDA3OjQzOjAyIiwicHJlZmVycmVkTGFuZ3VhZ2UiOm51bGwsInJvbGVzIjpbIlVTRVIiXX19LCJqdGkiOiI0OGE5NGIzNy1mMTJlLTQxNWQtYjM1Zi1kZDhmOThiMDQ4ZDcifQ.Cmgbd_xnUp8dPnIJvmUXmh5LYnHgHSk_n_0VzCn0k9r4WVNdsupb-MQqJvgOMg3K8si5mzhIjzLi9rZL5N_JwFXtpjKXKRVT7KF4mYfqF7bVNm6tkQg6CeAGhiuaMujhLhASS79LVBPKOv1tk79WuVu-VKHzyLS1h3yFQAsjLVQxA6_0MD7zKa1W3Nbhte6lHwgiNo1AlxuIJzP37-2saNb-aUy9DigmH3_C2oPqxpBu-YNnaekO5jNmbfucMinlpxCpEw-UvpvxI9Xk_9E73TNQE9acNQyyg_BxdnVbwDsR-kG5QXNrlEAxGm-1yY6w8Nvqxcp-3uoff6K0uKLUdQ'
90+
```
91+
92+
If everything is working as expected, the request should return a pleasant greeting. ;)
93+
94+
## Template Guide
95+
Here is a convenient list of steps to create a new application based on this template:
96+
97+
1. Fork this!
98+
2. Update __pom.xml__:
99+
- `groupId`
100+
- `artifactId`
101+
- `name`
102+
- `description`
103+
3. Update __application.yml__:
104+
- `auth.jwt.publicKeyUrl` - URL to fetch the JWT verification key
105+
4. Update __README.md__:
106+
- Replace current README with template - __README.template.md__
107+
- Remove template file
108+
- Update Project name and description in new README
109+

‎README.template.md

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
<h1 align="center"> Project Title </h1> <br>
2+
3+
<p align="center">
4+
Sample microservice description.
5+
</p>
6+
7+
8+
## Table of Contents
9+
10+
- [Introduction](#introduction)
11+
- [Features](#features)
12+
- [Requirements](#requirements)
13+
- [Quick Start](#quickstart)
14+
15+
16+
17+
18+
## Introduction
19+
20+
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
21+
22+
TODO: Replace with introduction
23+
24+
## Features
25+
TODO: Description of features
26+
27+
* Include a list of
28+
* all the many beautiful
29+
* web server features
30+
31+
32+
## Requirements
33+
The following software is required to run the application. It can be run locally or in a docker container.
34+
35+
### EGO
36+
A running instance of [EGO](https://github.com/overture-stack/ego/) is required to generate the Authorization tokens and to provide the verification key.
37+
38+
[EGO](https://github.com/overture-stack/ego/) can be cloned and run locally if no public server is available.
39+
40+
41+
### Local
42+
* [Java 8 SDK](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
43+
* [Maven](https://maven.apache.org/download.cgi)
44+
45+
46+
### Docker
47+
* [Docker](https://www.docker.com/get-docker)
48+
49+
50+
## Quick Start
51+
Make sure the JWT Verification Key is configured, then you can run the server in a docker container or on your local machine.
52+
53+
### Configure JWT Verification Key
54+
Update __application.yml__. Set `auth.jwt.publicKeyUrl` to the URL to fetch the JWT verification key. The application will not start if it can't set the verification key for the JWTConverter.
55+
56+
The default value in the __application.yml__ file is set to connect to EGO running locally on its default port `8081`.
57+
58+
### Run Local
59+
```bash
60+
$ mvn spring-boot:run
61+
```
62+
63+
Application will run by default on port `1234`
64+
65+
Configure the port by changing `server.port` in __application.yml__
66+
67+
68+
### Run Docker
69+
70+
First build the image:
71+
```bash
72+
$ docker-compose build
73+
```
74+
75+
When ready, run it:
76+
```bash
77+
$ docker-compose up
78+
```
79+
80+
Application will run by default on port `1234`
81+
82+
Configure the port by changing `services.api.ports` in __docker-compose.yml__. Port 1234 was used by default so the value is easy to identify and change in the configuration file.
83+
84+
85+
## Test
86+
TODO: Additional instructions for testing the application.
87+
88+
89+
## API
90+
TODO: API Reference with examples, or a link to a wiki or other documentation source.
91+
92+
## Acknowledgments
93+
TODO: Show folks some love.

‎src/main/resources/application.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
server:
2-
port: 8080
2+
port: 1234
33

44
auth:
55
jwt:

0 commit comments

Comments
 (0)