Add startup entrypoint, multi-stage build, and aligned CI/CD

[matthewhorridge]

Summary

This PR eliminates the manual Keycloak setup steps that operators currently have to perform after deploying WebProtege. It also modernises the build and release process to match the patterns used by other webprotege services.

Before this PR

After starting Keycloak, operators had to manually:

1. Import the realm via kcadm.sh create realms (~1 step)
2. Delete and recreate the username protocol mapper across 4 sub-steps because Keycloak's realm import silently drops the mapper config (keycloak#36065, keycloak#16289)
3. Verify the mapper was correct (~1 step)

Self-hosted deployments also had to manually edit the realm JSON or run kcadm commands to update redirect URIs, web origins, and the frontend URL to match their hostname.

Building the Docker image required Java and Maven installed locally to compile the SPI plugin before running docker build.

After this PR

Keycloak starts, imports the realm, fixes the mapper, and configures all URIs automatically. The operator just sets SERVER_HOST and runs docker compose up.

Building the image requires only Docker — docker build . handles everything.

What changed

Entrypoint script (entrypoint.sh)

A bash wrapper around kc.sh that runs after Keycloak starts:

1. Realm import — imports the webprotege realm via kcadm if it doesn't already exist. Keycloak does not auto-import from /opt/keycloak/import/; the entrypoint handles this explicitly.
2. Protocol mapper fix — checks whether the username mapper in the profile client scope correctly maps webprotege_username to preferred_username. If not, deletes and recreates it. This works around a Keycloak bug where the import drops the mapper's config dict.
3. Hostname-based URI patching — when SERVER_HOST is set, updates the webprotege client's baseUrl, redirectUris, webOrigins, and the realm's frontendUrl to match. This makes the image portable across local dev, staging, and production.

All operations are idempotent — on subsequent restarts, the script detects the correct state and skips modifications. SIGTERM/SIGINT are forwarded to the Keycloak process for graceful shutdown.

Multi-stage Dockerfile

• SPI build stage — compiles the authenticator plugin inside Docker using maven:3.9-eclipse-temurin-17. No local Java or Maven needed.
• jq download stage — fetches a static jq binary from GitHub releases (architecture-aware via TARGETARCH). Used by the entrypoint to parse kcadm JSON output.
• Final stage — based on keycloak/keycloak:26.1 as before, with the entrypoint set as the image's ENTRYPOINT.

Integration test (test-entrypoint.sh)

A self-contained test script that verifies the entrypoint end-to-end:

• Starts the container with a test SERVER_HOST
• Asserts: realm imported, mapper config correct, client URIs rewritten, frontend URL updated
• Restarts the container with a persistent volume
• Asserts: realm import skipped, mapper fix skipped, state unchanged

15 assertions total, runs in ~60 seconds. No host port needed (all checks run inside the container via docker exec).

CI/CD workflows

Aligned with the pattern used by other webprotege services:

• ci.yaml — runs on feature branches and PRs. Builds the image and runs the integration test.
• release.yaml — triggers on merge to main. Reads the version from pom.xml, strips -SNAPSHOT, releases that version, then bumps patch and adds -SNAPSHOT back for the next development cycle. Includes the integration test as a gate before pushing to Docker Hub. Notifies the deploy repo after a successful release.
• notify-deploy-project.yaml — reusable workflow that triggers update-compose.yml in webprotege-deploy to update the image version in docker-compose.yml.

Versioning

Follows the standard Maven -SNAPSHOT convention:

• pom.xml contains the next intended version with -SNAPSHOT (e.g. 2.0.0-SNAPSHOT)
• On merge to main, the workflow strips -SNAPSHOT and releases that version (2.0.0)
• After release, the workflow bumps patch and sets 2.0.1-SNAPSHOT
• Major/minor bumps: set the pom to X.Y.0-SNAPSHOT on your branch before merging

Branch protection

Added a "Protect Main" ruleset matching webprotege-backend-service: no deletion, no force push, PRs required, bot bypass for release commits.

Test plan

• Docker image builds successfully (docker build .)
• Integration test passes locally (15/15 assertions)
• First boot: realm imported, mapper correct, URIs patched
• Restart with volume: import skipped, mapper skipped, state preserved
• No host port required (no port conflicts)
• CI workflow runs on this PR