README: More info for adding framework to existing project

[katharinebrinker]

I ran into some speed bumps while adding the user framework to an existing project (using the Quick Start guide in the README file). Hopefully this info helps future devs in similar situations.

Background deets

• Java 21
• Spring Boot 4.0.6
• Spring User Framework 4.3.2
• db: postgres; already connected + working
• gradle
• configured with application.properties

Dependency / config issues

I added the following dependencies:

// listed as required
implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
implementation 'org.springframework.boot:spring-boot-starter-mail'
implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
implementation 'org.springframework.boot:spring-boot-starter-security'
implementation 'org.springframework.retry:spring-retry'

// listed as additional for testing
testImplementation 'org.springframework.boot:spring-boot-data-jpa-test'
testImplementation 'org.springframework.boot:spring-boot-webmvc-test'
testImplementation 'org.springframework.boot:spring-boot-starter-security-test'

spring-retry does not work

spring-retry could not be found; that dependency needed to be commented out (compile-time error Could not find org.springframework.retry:spring-retry)

Needed additional OAUth2 dependency

Even though I'd included spring-boot-starter-security already, I needed to explicitly add an OAuth2 dependency (implementation org.springframework.boot:spring-boot-starter-oauth2-client)

Partial email config needed

Step 4 says that email configuration is optional but recommended; however, a JavaMailSender bean won't be configured (resulting in a runtime error) unless spring.mail.host is in application.properties (NOTE: I call out the application.properties part specifically, in case it behaves differently than an application.yml). The value can be blank (spring.mail.host=) and no other info (port / username / etc) is needed

For the Thymeleaf noobs (i.e., me and others like me)

Adding the user framework via gradle does not add the HTML templates to an existing project; though the guide says that default templates are provided, in my case I had to grab some from the demo app

[devondragon]

Thanks for the detailed write-up @katharinebrinker — every one of these was a real problem, not just a docs nit. PR #311 addresses all four:

1. spring-retry version — pinned to 2.0.12 in the README (matches what the library is built against). Spring Boot's BOM doesn't always manage this artifact, so we shouldn't rely on it.
2. OAuth2 dependency — added spring-boot-starter-oauth2-client to the required-deps list. It's unconditionally wired into the security chain, so it has to be on the classpath even when social login is disabled. README now calls this out explicitly.
3. spring.mail.host requirement — this was a real bug, not just a docs issue. MailService had JavaMailSender as a hard constructor dep, so the app couldn't start without mail configured. Refactored to ObjectProvider<JavaMailSender> — mail is now genuinely optional: send operations log a warning and no-op when no sender is configured. README Step 4 updated to describe the degraded behavior.
4. HTML templates — you were right, the library only ships email templates; the "default HTML templates" claim in Step 9 was wrong. Updated Step 9 to direct users to the demo app's templates/user/ directory and listed the files.

The issue will auto-close when #311 merges. Thanks again for taking the time to file this — these were exactly the kinds of speed bumps that drive people away in their first 30 minutes with a library.

[katharinebrinker]

Thanks for the quick fix, and for all the background info! 🙌