Case UI

The Case UI is an optional web front-end served next to the application. It is a static single-page app in an nginx container: no database, no license, no state of its own. Everything it shows comes from the application, requested by the browser.

Because it carries no state, it is also the cheapest component to install, restart and upgrade — replacing the container is the whole procedure.

Where it runs

The Case UI runs as an additional service in the same Compose project as the application, listening on port 3000. The reverse proxy publishes it at the root of the application’s host name, /, while the application stays under /${PREFIX}/.

Caller	Address
Browser, Case UI	https://<your host>/ via the reverse proxy
Browser, application	https://<your host>/${PREFIX}/ via the reverse proxy, unchanged
Host, for troubleshooting	http://127.0.0.1:3000

Serving both from the same host name is required, not a convenience. The Case UI and the application then share an origin, so the browser’s requests to the application need no CORS configuration, and the session cookie from the application’s login is sent along with them. On a separate host name neither holds. It also means no second certificate.

The image

The image is pulled from the same registry as the others, with the login from Container Registry:

docker pull registry.onstackit.cloud/rms/rms-case:0.28.49

Use the tag issued for your installation.

The Compose service

Add this service to docker-compose.yml:

  case-ui:
    image: registry.onstackit.cloud/rms/rms-case:0.28.49
    container_name: rms-case0
    restart: unless-stopped
    environment:
      TZ: ${TZ}
      # Path the application is published under — the same ${PREFIX} the
      # application uses. The app calls /query and /dms/ktx/* beneath it.
      RAP_PATH: /${PREFIX}
      GIS_MAP_URL: ${GIS_MAP_URL}
    ports:
      - "3000:3000"
    healthcheck:
      test: ["CMD", "curl", "-fsS", "-o", "/dev/null", "http://localhost:3000/healthz"]
      interval: 30s
      timeout: 5s
      retries: 3
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "5"

GIS_MAP_URL is not in rap.config.sh — add it to the installation directory’s .env next to TZ and PREFIX:

echo 'GIS_MAP_URL=<URL provided by Rulemapping Solutions>' >> .env
docker compose config      # must resolve every variable

Variable	Required	Meaning
RAP_PATH	yes	Path the application is published under — the same value as :prefix in rw/ktbs.cl. Also the redirect target when a request comes back 401.
GIS_MAP_URL	yes	GIS middleware iframe URL, used only by the map tile. It is loaded by the browser, so it has to be reachable from the client network, not from the server. Where the map is not used, any valid URL satisfies the check.
BASE_PATH	no (default /)	Path the proxy publishes this container under. Leave it unset: the Case UI is published at /, which is the default.

Start it:

docker compose up -d case-ui
docker compose ps case-ui

The service must reach state healthy.

Verify the container

curl -fsS http://127.0.0.1:3000/healthz; echo
curl -fsS http://127.0.0.1:3000/config.js

Expected: ok, then a window.__APP_CONFIG__ block holding exactly the rapPath and gisMapUrl configured above. Different values mean the container is still running with an older environment — docker compose up -d --force-recreate case-ui.

Reverse proxy

Add a location / for the Case UI to the server block that already serves the application. The application’s own location stays as it is. For nginx, with your own prefix in place of PREFIX — nginx does not expand shell variables:

...

# New: the Case UI, everything outside /PREFIX/
location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host              $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
}

...

nginx picks the longest matching prefix, so requests under /PREFIX/ still reach the application and only the rest goes to the Case UI. Order in the file does not matter. Before this change nothing was served outside /PREFIX/, so location / takes nothing away from the application.

The same X-Forwarded-Proto: https requirement as for the application applies, see Maintenance.

Apply the change:

sudo nginx -t && sudo systemctl reload nginx

nginx -t has to pass before the reload. If it fails, the running configuration is untouched.

Verify from outside

source ./rap.config.sh

curl -fsS -o /dev/null -w '%{http_code}\n' \
  "https://$PREFIX.$DOMAIN/healthz"

curl -fsS "https://$PREFIX.$DOMAIN/config.js"

curl -s "https://$PREFIX.$DOMAIN/$PREFIX/" | grep -c __ac_password

Expected: 200, then the same window.__APP_CONFIG__ block as in Verify the container, then a count of at least 1. The last check proves that the application is still reachable under its prefix; 0 means location / is catching its requests — check that the application’s location /PREFIX/ is still in the same server block.

Then open https://<your host>/ in a browser. The Case UI reporting “Keine Konfiguration vorhanden” is the successful outcome of this page: it proves the app loaded, reached the application and authenticated. What it still needs is its dashboard configuration, which is done inside the application and is not part of the installation.

An error page instead means the application is not reachable under RAP_PATH; a redirect to the login page means the browser has no session yet.

Upgrading

$EDITOR docker-compose.yml      # set the new tag
docker compose pull case-ui
docker compose up -d case-ui

Nothing is persisted in the container, so no backup or migration step belongs to an upgrade here. The dashboard configuration lives in the application and is unaffected.

Troubleshooting

Symptom	Cause
Container exits at once, log says RAP_PATH is required	The variable is missing from the service’s environment:, or .env does not define it.
Healthy container, blank page in the browser	BASE_PATH is set to something other than /. Remove it and recreate the container.
Page loads, every request answers 401	RAP_PATH does not match the path the application is published under, or the Case UI is served from a different host name than the application, so the session cookie is not sent.
Application under /PREFIX/ shows the Case UI	The application’s location /PREFIX/ is missing or misspelled in the server block.
Map tile empty, everything else fine	GIS_MAP_URL is not reachable from the browser’s network.