Skip to content

Commit 7c0cf97

Browse files
wiversonwiverson
committedSep 8, 2021
First commit.
1 parent 678ac7b commit 7c0cf97

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

66 files changed

+23529
-0
lines changed
 

‎README.md

+209
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# Easy, Powerful Full Stack Spring Boot
2+
3+
Build slick, fast Spring Boot full stack web applications easily as a solo developer.
4+
5+
This project is specifically designed to make it easy to build a modern web application with Spring Boot.
6+
7+
Here's a list of features:
8+
9+
- Uses [Supabase.io](https://supabase.io) as the core for RDBMS, auth, storage.
10+
- [Supabase is an open source platform](https://github.com/supabase/supabase) that offers
11+
hosted [Postgres](https://www.postgresql.org/) with built-in integration with a variety of services, including
12+
[simplified authentication](https://supabase.io/docs/guides/auth)
13+
and [storage](https://supabase.io/docs/guides/storage).
14+
- This project specifically uses Supabase for auth (including seamless Spring Security support!) and as a hosted
15+
Postgres instance.
16+
- There's a lot more on Supabase later in this document. :)
17+
- Because Supabase is just Postgres, that means you can use all of [IntelliJ's](https://www.jetbrains.com/idea/) RDBMS
18+
features, including [JPA Buddy](https://www.jpa-buddy.com/).
19+
- This means that everything is type-aware (auto-complete FTW!) from the RDBMS through the Java code and into the
20+
Thymeleaf templates!
21+
- Reconfigured the [Thymeleaf](https://www.thymeleaf.org/) settings for compatibility
22+
with [Pinegrow](https://pinegrow.com/) visual HTML builder
23+
- Uses [Bootstrap](https://getbootstrap.com/) as a default CSS framework
24+
- Drop in a [new Bootstrap theme](https://github.com/thomaspark/bootswatch) with minimal fuss!
25+
- If you want to switch to TailwindCSS instead, no big deal.
26+
- Use [HTMX](https://htmx.org/) and Thymeleaf Fragments to provide
27+
[rich, dynamic partial page updates](https://changenode.com/articles/easy-full-stack-java)
28+
without using any complicated JavaScript frameworks.
29+
- Stateless by default - uses [Supabase JWT](https://supabase.io/docs/learn/auth-deep-dive/auth-deep-dive-jwts) for
30+
authorization, so the project defaults to turning off Java sessions to improve ease of scaling.
31+
- TIP: Use service level [Spring Boot caching](https://spring.io/guides/gs/caching/) instead of the antiquated
32+
session API to take the load of a database instead the session API.
33+
34+
# Screenshots
35+
36+
The default theme is the open source Bootstrap
37+
theme [Darkly](https://github.com/thomaspark/bootswatch/tree/v5/dist/darkly), which just happens to be very similar to
38+
the default Supabase theme. You can swap in another theme (e.g. another [Bootswatch](https://bootswatch.com/) theme) or
39+
build your own via SASS or the Pinegrow Design editor.
40+
41+
## Basic Features
42+
43+
![Home Screen](src/main/site/home-screen.png)
44+
45+
The default home screen displayed to the user.
46+
47+
![Sign In](src/main/site/sign-in.png)
48+
49+
Log in with either a social provider or email/password. Supabase supports
50+
many [other providers](https://supabase.io/auth)!
51+
52+
![Create Account](src/main/site/create-account.png)
53+
54+
Create an account quickly and easily. Supabase sends the various emails (confirmation, forgot password) for you. If you
55+
want to use your own SMTP server, pop in the SMTP credentials into Supabase.
56+
57+
![Forgot Password](src/main/site/forgot-password.png)
58+
59+
This project includes the JavaScript to handle the forgot password flow.
60+
61+
![Logged In User](src/main/site/logged-in-user.png)
62+
63+
Logged in Supabase information is available both via standard Spring Security (via principal) and via a bean wrapper (
64+
makes it easier to work with in Thymeleaf).
65+
66+
## Thymeleaf Visual Editing
67+
68+
![Create Account](src/main/site/pinegrow-create-account.png)
69+
70+
Shows how the Create Account page can be viewed visually. Use the Pinegrow built-in HTML code editor or tab back and
71+
forth with IntelliJ.
72+
73+
![Master Layout](src/main/site/pinegrow-master-layout.png)
74+
75+
This is the master layout used throughout the template. Also can be edited visual and/or via code editor.
76+
77+
![Mobile and Bootstrap Blocks](src/main/site/pinegrow-mobile-bootstrap-blocks.png)
78+
79+
Pinegrow handles responsive design quickly and easily. Just press a single keystroke to view the different breakpoints.
80+
Visually assign styling based on breakpoints.
81+
82+
# Getting Started
83+
84+
## Basics
85+
86+
You'll need Java 16+ and Maven.
87+
88+
## Supabase
89+
90+
You will need to set up a new [Supabase.io](https://supabase.io/) project. You can start with the free starter version.
91+
Eventually you can switch to either a [paid account](https://supabase.io/pricing) or set up your
92+
own [self-hosted version](https://supabase.io/docs/guides/self-hosting).
93+
94+
## Configuration
95+
96+
Set the following environment values so Maven and Spring Boot can find them. Tip: if you declare them in a .profile on
97+
macOS, IntelliJ will pick them up.
98+
99+
| VALUE | Typical Values |
100+
| ----- | --- |
101+
| `SUPABASE_DATABASE_URL` | jdbc:postgresql://db.PROJECT.supabase.co/postgres |
102+
| `SUPABASE_DATABASE_USER` | postgres |
103+
| `SUPABASE_DATABASE_PASSWORD` | Same as your Supabase login password. |
104+
| `SUPABASE_URL` | https://PROJECT.supabase.co |
105+
| `SUPABASE_ANON_KEY` | A JWT with the role of anon. Verify it at https://jwt.io/ |
106+
| `SUPABASE_JWT_SIGNER` | The TOP SECRET key used for signing JWT from Supabase. DO NOT SHARE THIS - anyone who has this can create new identity JWTs - basically, this is a super password that would allow anyone to impersonate anyone on the site! |
107+
108+
## Database
109+
110+
By default, this template points to the Supabase table and expects to find a user table and a todo table. If you are
111+
playing around, you might want to try creating a matching table. Otherwise, just go ahead and delete
112+
the [todo entity and query files](https://spring.io/guides/gs/accessing-data-jpa/):
113+
114+
`src/main/java/com/changenode/frisson/data/ToDo.java`
115+
`src/main/java/com/changenode/frisson/query/TodosEntityQuery.java`
116+
117+
## IntelliJ Setup
118+
119+
This project uses the src/main/resources/public directory to store the html files.
120+
121+
![IntelliJ Web Module Setup](src/main/site/intellij-web-module-setup.png)
122+
123+
In IntelliJ, make sure you set up the Web module to point at src/main/resources/public directory. Otherwise you will get
124+
errors related to paths in IntelliJ.
125+
126+
# Help
127+
128+
This entire project is built on top of a large number of well-documented open source projects, such as Spring Boot,
129+
Bootstrap, Postgres, Thymeleaf, Supabase, and HTMX, just to name a few. Most of your issues or questions are probably
130+
going to be solved by the usual combination of the project documentation, Google, Stack Overflow, etc.
131+
132+
That said, here are some options specific to this project:
133+
134+
- Check out the [discussion board](https://github.com/ChangeNode/frisson/discussions).
135+
- File an [issue](https://github.com/ChangeNode/frisson/issues).
136+
137+
If you need consulting support, [feel free to reach out](https://changenode.com/contact).
138+
139+
# Additional Supabase Information
140+
141+
## Supabase PostREST and Spring Boot
142+
143+
By default, Supabase makes data available to the browser using [PostREST](https://postgrest.org/) - an application that
144+
automatically generates REST endpoints for a relational database.
145+
146+
Java web frameworks, on the other hand, usually connect directly to the database.
147+
148+
Which is better? If you are a Java developer used to working with Spring Boot and Spring data repositories, just use
149+
that. Keep your tables private in Supabase connect just like you would with any ordinary Postgres instance.
150+
151+
If you want to use PostREST, that's fine - just be absolutely sure you are setting up row-level security correctly!
152+
153+
# Remember Me
154+
155+
The "Remember Me" setting in the login user interface, if checked, will store the JWT in a cookie, which will then allow
156+
the server to immediately render the logged-in user as long as the JWT has not expired.
157+
158+
The default for JWT tokens on Supabase is 3600 seconds (1 hour). As long as the user is actively clicking around on the
159+
website, the Supabase.js client will automatically refresh with new JWT tokens.
160+
161+
This means, however, that the "Remember Me" feature will only work for up to 1 hour. If you want to extend this, go to
162+
the Authentication -> Settings -> JWT Expiry and change it to something longer. The maximum setting allowed (one week)
163+
means that as long as the user logs into the site at least once a week, they will effectively never have to log in
164+
again.
165+
166+
The only downside is that you can't easily revoke a JWT once issued. So, if you extend the JWT session, that's the login
167+
time. If you want to implement some kind of instant user ban, you can still use JWT but you will need to add additional
168+
logic.
169+
170+
# More Information
171+
172+
### Bootstrap Themes
173+
174+
This project uses the Bootstrap 5.1 theme from:
175+
176+
https://github.com/thomaspark/bootswatch/tree/v5/dist/darkly
177+
178+
You can drop in other themes from:
179+
180+
https://github.com/thomaspark/bootswatch/
181+
182+
Or you can use the built-in Pinegrow SASS compiler to build your own Bootstrap themes.
183+
184+
### SVG Icons
185+
186+
The SVG Icons in this project are from:
187+
188+
https://ionic.io/ionicons
189+
190+
### Reference Documentation
191+
192+
For further reference, please consider the following sections:
193+
194+
* [Official Apache Maven documentation](https://maven.apache.org/guides/index.html)
195+
* [Spring Boot Maven Plugin Reference Guide](https://docs.spring.io/spring-boot/docs/2.5.3/maven-plugin/reference/html/)
196+
* [Create an OCI image](https://docs.spring.io/spring-boot/docs/2.5.3/maven-plugin/reference/html/#build-image)
197+
* [Spring Boot DevTools](https://docs.spring.io/spring-boot/docs/2.5.3/reference/htmlsingle/#using-boot-devtools)
198+
* [Spring Web](https://docs.spring.io/spring-boot/docs/2.5.3/reference/htmlsingle/#boot-features-developing-web-applications)
199+
* [Thymeleaf](https://docs.spring.io/spring-boot/docs/2.5.3/reference/htmlsingle/#boot-features-spring-mvc-template-engines)
200+
* [Spring Data JPA](https://docs.spring.io/spring-boot/docs/2.5.3/reference/htmlsingle/#boot-features-jpa-and-spring-data)
201+
202+
### Guides
203+
204+
The following guides illustrate how to use some features concretely:
205+
206+
* [Serving Web Content with Spring MVC](https://spring.io/guides/gs/serving-web-content/)
207+
* [Handling Form Submission](https://spring.io/guides/gs/handling-form-submission/)
208+
* [Accessing Data with JPA](https://spring.io/guides/gs/accessing-data-jpa/)
209+

0 commit comments

Comments
 (0)