Wicket Playground

This project houses some PoC for integrations of frameworks, protocols and 3rd-party service outside the Apache Wicket ecosystem.

The application provides the following features:

• Spring Boot application bootstrapper
• Pluggable Wicket modules
• React dashboard island within a Wicket page
• 3rd-party PDF preview service embedded in an iframe
• Bootstrap 5
• Wicket Webjars
• Static resource compressors
• Sass-compiled static resources
• Render JavaScript resources to footer
• Wicket test suites
• OAuth2 secured Wicket page
• Profile-driven environments
• Keycloak smoke test
• Profile-driven test executions
• Social Login for HackMD's CodiMD with Keycloak
• Embed CodiMD notes in a Wicket page
• JWT role claim mapping for Spring Security and Wicket
• Wicket Bootstrap 5 Modal component
• Native OIDC front-channel logout
• Wicket Bootstrap form components with server-side validation and feedback messages
• Keycloak Docker Compose service healthcheck
• Clean dependency management

To enable authentication start the Sprint Boot application with the Spring profile wicket,keycloak active. To do so, override the application.yml or use the runtime property -Dspring.profiles.active=wicket,keycloak. Also use the corresponding Docker Compose file in addition to the default one. Start the entire stack using docker compose -f compose.yaml -f compose.keycloak.yaml up -d.

Keycloak

Keycloak is an authorization provider that implements the OAuth2 and OpenID Connect protocols. It manages software clients, users, their roles and claims for the project.

Users

Keycloak is preconfigured with a variety of users that are more or less useful. The username-password-combination adult:B4nk might be the only one you ever need for development and manual testing.

Username	Password	Description	Realm	URL
adult	B4nk	Realm superuser	local	http://localhost:8180/admin/local/console/
landlord1	Prop3r7y1	Keycloak administrator	master	http://localhost:8180/admin/master/console/

Configuration Export

This section explains how to export updated configurations so that they can be managed by Git. The development configuration for Keycloak is part of this project to distribute changes through Git.

First, make sure your development stack is up and running. Perform your necessary changes in the Keycloak web UI. Next, perform the following command. This will start a new Keycloak instance inside the running container.

docker compose -f compose.yaml -f compose.keycloak.yaml exec keycloak sh -c \
  "cp -rp /opt/keycloak/data/h2 /tmp ; \
  /opt/keycloak/bin/kc.sh export --dir /opt/keycloak/data/import --realm local --users realm_file \
    --db dev-file \
    --db-url 'jdbc:h2:file:/tmp/h2/keycloakdb;NON_KEYWORDS=VALUE'"

React island

Maven is configured to compile the React sources into the Classpath when using targets like compile or package. Any subsequent changes to the React code need a re-package so the new stuff gets picked up by Wicket. You may also just run the vite dev server.

CodiMD Pads

CodiMD is an open-source, collaborative and self-hosted service for managing notes in Markdown syntax.

Without Authentication

Start the application and navigate to http://localhost:8080/note to see an embedded CodiMD pad within a Wicket page.

With Authentication

Unfortunately, the integration into other services and a Docker environment is finicky and has a few caveats and potential deal-breaker.

1. Hostname

Like any other OAuth2 client, CodiMD needs to know where to find the OAuth2 authorization server, but neither CodiMD nor Keycloak separate their configuration endpoints that is easily compatible with a Docker setup. So both services must communicate via the default gateway using the host.docker.internal hostname. You may have to add the host to you localhost IP address 127.0.0.1 in /etc/hosts.

If anyone has a way to resolve the workaround, feel free to contribute, write an issue or DM me. I'm so desperate for a clean and convenient solution. Btw, running the Docker Compose services in network mode host is not an option, because it defeats the purpose of Docker IMO and doesn't work on macOS anyway.

2. SSO

The Wicket page directly reference a note ID. As long as you are not logged in CodiMD will throw an Internal Server Error and logs that the URL is not valid. Because of the first issue, SSO cannot work unless host.docker.internal is used everywhere. To work around the issue, navigate to http://localhost:8280 and login a second time. Get back to http://localhost:8080/note afterward and reload if you need to.

Footnotes

1. Corresponds to the values of KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD, set for Composes' keycloak. ↩ ↩²