Support HTTPS/WSS for the deployed stack (nginx TLS termination)

[johardi]

Background

The deployed stack currently serves everything on plain HTTP via nginx on port 80. Until recently, docker-compose.yml configured the frontend to open a TLS WebSocket:

webprotege.websocketUrl: wss://${SERVER_HOST}/wsapps

but no TLS listener exists (nginx is bound only to 80/tcp, no certificate is configured, and the image doesn't listen on 443). The browser's wss:// handshake failed silently, so no events reached the frontend — stale hierarchy trees after create-subclass / create-property, etc.

As a short-term fix, webprotege.websocketUrl has been changed to ws://${SERVER_HOST}/wsapps, matching the rest of the stack which is all http://. Events flow again.

Why follow-up matters

Plain ws:// / http:// is fine for local Docker Compose development, but not for any shared or production-style deployment:

• Keycloak is already configured with KC_PROXY: edge, meaning it expects TLS to be terminated at the edge proxy (nginx). Serving it behind http:// is a misalignment waiting to bite.
• Any real browser context (non-localhost) will treat ws:// + sensitive tokens as insecure; some environments will actively block it.
• Mixed-content warnings / cookie Secure flag behavior differ between HTTP and HTTPS, and we don't want to discover those differences in production.

Scope

• webprotege-deploy/nginx/nginx.conf: add a server { listen 443 ssl; ... } block mirroring the current :80 server; reference ssl_certificate + ssl_certificate_key from a mountable path; optionally add a 301 redirect from :80 to :443.
• webprotege-deploy/docker-compose.yml:
  • nginx service — expose 443:443, mount cert files read-only into /etc/nginx/certs/.
  • Flip the http:// URLs in the webprotege-gwt-ui-server, webprotege-gwt-api-gateway, webprotege-authorization-service, and webprotege-user-management-service envs to https:// where they reference ${SERVER_HOST} (Keycloak issuer URIs, logout URLs, file upload URL, allowed origin).
  • Flip webprotege.websocketUrl back to wss://${SERVER_HOST}/wsapps.
• README.md: mkcert-based instructions for generating a locally-trusted cert for ${SERVER_HOST} so developers don't see browser warnings.

Acceptance criteria

• docker compose up brings the stack up on https://${SERVER_HOST} with a valid (local-dev) cert.
• Browser DevTools → Network → WS shows 101 Switching Protocols on wss://${SERVER_HOST}/wsapps.
• Creating a subclass updates the class-hierarchy tree immediately (no manual refresh).
• Creating a new object/data/annotation property updates the property-hierarchy tree immediately.
• No mixed-content warnings in the browser console.
• Keycloak login + logout round-trip works end-to-end.

[alexskr]

Hey @johardi — I've been working on the same problem from a different angle for the past couple of weeks. Want to sync up here before either of us writes more code, because the approach I took is architecturally different and I'd rather we converge than land competing PRs.

What I built

A staging instance at https://webprotege-staging.stanford.edu/ behind an externally managed nginx that terminates TLS at the host level. webprotege-nginx stays on plain HTTP and binds 127.0.0.1:8080 only; the host nginx terminates TLS and proxies to it.

Reasoning: typical Stanford on-prem and cloud deployments (AWS ELB, GCP LB) terminate TLS at an external proxy / load balancer anyway, so externalizing it makes the stack portable across topologies without re-rolling the cert flow per environment.

That's the opposite of what this issue proposes — instead of teaching webprotege-nginx to terminate TLS itself, my approach keeps it on plain HTTP behind an external terminator.

Code:

• https://github.com/alexskr/webprotege-deploy
• https://github.com/alexskr/webprotege-nginx (forked, X-Forwarded-Proto trust patch)
• https://github.com/alexskr/webprotege-keycloak (forked, scheme-aware entrypoint)

Six HTTPS-only bugs I had to fix

All invisible in HTTP-only dev, blocking in any TLS-terminated topology — both your proposed in-stack-TLS path and my external-TLS path hit the same set:

1. webprotege-nginx: proxy_set_header X-Forwarded-Proto $scheme overwrote upstream https with http. Fixed in my fork with a trust-upstream-if-present map.
2. webprotege-keycloak entrypoint: patched realm frontendUrl + webprotege client redirectUris/webOrigins/baseUrl with hardcoded http://. Fixed via new PUBLIC_SCHEME env var.
3. KC_HOSTNAME as bare hostname: Keycloak emits http URLs in back-channel discovery doc fetches (no X-Forwarded-* on the internal bridge). Fix: full-URL form KC_HOSTNAME=${PUBLIC_SCHEME}://${SERVER_HOST}/keycloak.
4. hostname: ${SERVER_HOST} on webprotege-nginx (in docker-compose.yml): Docker's embedded DNS on a user-defined bridge resolves siblings' hostname field, so anything doing back-channel HTTPS to the public hostname got connection-refused on a bridge IP instead of the host's public IP.
5. webprotege-gwt-ui-server: plain Tomcat 9 + the legacy org.keycloak.adapters Java adapter, with no RemoteIpValve in server.xml. request.getScheme() returned http, adapter built redirect_uri=http://..., Keycloak rejected with "Invalid parameter: redirect_uri."
6. Keycloak master realm sslRequired=external (stock default) blocked admin console over HTTP — dev-only symptom but real.

Every one of these is the kind of bug an opt-in HTTPS dev path would let contributors catch on their laptop before staging. The acceptance criteria in this issue (wss works, hierarchy events flow, no mixed content, Keycloak round-trip) are satisfied by both topologies, but several of these bugs need fixing regardless of which TLS path we pick.

The architectural choice

Three plausible paths, in increasing order of how cleanly they handle the "different deployment targets use different TLS terminators" problem:

A. TLS inside webprotege-nginx — what this issue proposes. Simplest. One image, one cert mount. Works for self-contained docker compose up and for LB-fronted prod (where the container's 443 listener just sits unused). Caveat: webprotege-nginx now has two concerns mixed in one image — request routing and TLS termination — which means it has to be rebuilt for nginx-config changes that have nothing to do with TLS.

B. Separate TLS-terminator container — a dedicated sidecar (webprotege-tls, or just stock Caddy / Traefik) that terminates TLS and proxies to webprotege-nginx:80. Shipped via compose overlay (docker-compose.tls.yml or similar). webprotege-nginx stays single-purpose and just trusts upstream X-Forwarded-Proto. In dev the sidecar mounts mkcert certs; in single-host prod it handles letsencrypt; in LB-fronted prod the sidecar is disabled and the LB does TLS directly. Clean separation of concerns, more portable across deployment shapes.

C. Skip the in-stack story entirely — assume an external TLS terminator is always present (managed outside compose). What I built. Works fine for any deployment that already has TLS infrastructure; awkward for docker compose up dev where you'd need to bring your own terminator.

After working through it, I'd lean (B) — webprotege-nginx stays simple, TLS becomes a swappable layer, and the same compose-overlay pattern we use for the prod overlay handles it. Caddy as the sidecar would auto-handle letsencrypt in single-host prod and trust-locally-installed-CA in dev with effectively no config.

If you want to stay on (A), I can fold my X-Forwarded-Proto trust patch into the upstream webprotege-nginx along with the listen 443 ssl block. But (B) feels like the architecturally cleaner answer if we're going to revisit this anyway.

Smaller notes

• KC_PROXY: edge (currently in the stack) is the legacy Keycloak setting, deprecated since Keycloak 21+. The current replacement is KC_PROXY_HEADERS=xforwarded. Worth converging regardless of which TLS path we pick.
• The mkcert-for-local-dev direction in your Scope section is exactly what I was planning to propose. Looks like we agree on that part.
• I've got a longer write-up framing an optional opt-in HTTPS dev layer (rather than HTTPS-by-default) — happy to share separately if useful.

Where to go from here

Before either of us writes more code, can we agree on (A) / (B) / (C)? I'm happy to fold my external-TLS work into your in-stack approach, write up (B) properly if there's interest, or step back and let you take the lead on (A) — whichever fits how you want to land this. Just want to avoid two parallel PRs landing different stories.