feat: capture demo mail in Mailpit so the Docker stacks show email verification

[devondragon]

Closes #86

Both Docker stacks ran docker-mailserver with SMTP_ONLY=1: a relay with no route to real inboxes. That is why #85 had to set USER_REGISTRATION_SENDVERIFICATIONEMAIL=false, and why the demo could never show registration verification, password reset, or the two-hop flow most adopters actually ship.

This replaces it with Mailpit, which captures outbound mail and serves it as a web inbox on localhost:8025.

Changes

• compose.yaml, docker-compose-keycloak.yml: docker-mailserver → axllent/mailpit:v1.30. The app talks plain SMTP to mailpit:1025, auth and STARTTLS off. Neither stack overrides sendVerificationEmail any more, so the base default of true applies.
• Removed with it: mailserver.env, the ./config/ bind mount, the maildata/mailstate/maillogs volumes, NET_ADMIN/SYS_PTRACE, and published ports 25/587. SELINUX_LABEL went with the bind mount, so docker compose no longer warns that it is unset.
• Docs: README quick start, docs/CONFIGURATION.md mail section, docs/AUTHENTICATION.md registration and Keycloak walkthroughs, docs/DEVELOPMENT.md stack descriptions, keycloak/README.md (ports table plus a form-registration walkthrough). Also corrected a stale compose.yaml:86-90 citation to 72-76.
• messages.properties: page.title.registration-ending-verification → registration-pending-verification. The template always asked for the latter, so the pending page rendered ??page.title.registration-pending-verification_en?? as its title. It survived because no documented run path reached that page until now.

One deviation from the ticket

The ticket proposed a GET /livez healthcheck. The implementation uses ["CMD", "/mailpit", "readyz"] instead. Either would have worked, and readyz is preferred for a different reason than I first gave: it is exactly what the image bakes in as its own default HEALTHCHECK, so the compose block just makes the upstream default explicit.

Correction. An earlier version of this description said the image is built from scratch with no curl/wget/nc and that there is no /livez. Both claims were wrong. axllent/mailpit:v1.30 is Alpine-based with busybox wget and nc (only curl is absent), and v1.30.7 serves both /livez and /readyz over HTTP on 8025 — the ticket's proposed probe would have been fine. mailpit livez is not a CLI subcommand, which is the only sense in which the original claim held. The compose comments carried the same error and are corrected in cc0949b.

Verification

Driven in a real browser against both stacks, not just asserted:

Criterion	Result
compose.yaml: register → read mail at :8025 → click verify link → log in	Pass
compose.yaml: password reset via the emailed link	Pass; new password logs in
Keycloak stack: both flows	Pass
Keycloak OIDC login (demo/demo) still works	Pass
./gradlew test	BUILD SUCCESSFUL, 309 tests, 0 failures, 0 errors

Mailpit's readyz probe gated myapp-main correctly in both stacks, and the emailed links point at http://localhost:8080 (from user.security.appUrl), so they work from the host browser.

Playwright is unaffected as the ticket predicted: it runs local,playwright-test outside Docker, and that profile disables both the verification and password-reset emails.

Framework-side limitation found while verifying

The resend-verification page does not work, and it is not fixable here. UserAPI.resendRegistrationToken in ds-spring-user-framework:5.3.0 binds the full registration UserDto, whose firstName, lastName, password, and matchingPassword are @NotBlank. The email-only payload resend-verification.js posts is rejected with HTTP 400 and no mail is sent:

Validation failed for argument [0] in ... UserAPI.resendRegistrationToken(UserDto, HttpServletRequest)
with 4 errors: [... 'matchingPassword': rejected value [null] ...] [... 'password' ...]
[... 'lastName' ...] [... 'firstName' ...]

The ticket listed resend among the flows the Docker demo could not show. It still cannot, for a different reason. Documented as a known limitation in docs/CONFIGURATION.md and docs/AUTHENTICATION.md; tracked upstream.

[Copilot]

Pull request overview

This PR updates the Docker demo stacks to use Mailpit (SMTP capture + web inbox) so the demo can exercise real email-driven flows like registration verification and password reset, and aligns documentation/messages accordingly.

Changes:

• Replaces docker-mailserver with axllent/mailpit in both Docker stacks, updating app SMTP settings and healthchecks.
• Restores/relies on the default user.registration.sendVerificationEmail=true so the Docker path can show verification end-to-end.
• Fixes an i18n key mismatch for the pending-verification page title and updates docs to reference the Mailpit inbox flow.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/main/resources/messages/messages.properties	Fixes the pending-verification page title key to match the template’s expected message key.
README.md	Updates Docker quick start to instruct reading verification/reset emails via Mailpit on localhost:8025.
mailserver.env	Removes the old docker-mailserver env file (no longer needed with Mailpit).
keycloak/README.md	Documents Mailpit inbox URL and adds a form-registration walkthrough for the Keycloak stack.
docs/DEVELOPMENT.md	Updates stack descriptions and references to reflect Mailpit usage and updated compose citations.
docs/CONFIGURATION.md	Updates the “Mail” section to describe Mailpit behavior in Docker stacks and notes the resend limitation.
docs/AUTHENTICATION.md	Updates registration and password-reset walkthroughs to reference Mailpit and documents resend limitation.
docker-compose-keycloak.yml	Swaps mail service to Mailpit, updates ports/healthcheck, and points app SMTP to mailpit:1025.
compose.yaml	Swaps mail service to Mailpit, updates ports/healthcheck, and points app SMTP to mailpit:1025.
CHANGELOG.md	Adds an entry describing the Mailpit migration and the i18n key fix.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[devondragon]

Already fixed in cc0949b, which landed after this review ran. The entry now lists only registration-verification and password-reset, and points at the known-limitation note for resend.