Refactor GrampsWeb subpath handling: move all patching to nginx sub_filter (STI-98)

Replace fragile container-side sed/JS patching with comprehensive nginx sub_filter
rules. The container now only handles admin user creation on startup. All SPA route
prefixing is done in nginx via a History API interceptor injected into HTML responses.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

compose.dev.yml

@@ -197,11 +197,36 @@ services:
       - GRAMPSWEB_ADMIN_EMAIL=admin@localhost
       - GRAMPSWEB_ADMIN_PASSWORD=gramps_dev_password
       - GRAMPSWEB_TREE=Stiftung
-      - GRAMPSWEB_BASE_URL=/
+      - GRAMPSWEB_BASE_URL=http://localhost:18090
       - GRAMPSWEB_CELERY_CONFIG__broker_url=redis://redis:6379/0
       - GRAMPSWEB_CELERY_CONFIG__result_backend=redis://redis:6379/0
       - GRAMPSWEB_RATELIMIT_STORAGE_URI=redis://redis:6379/1
       - GRAMPSWEB_NEW_DB_BACKEND=sqlite
+    command:
+      - sh
+      - -c
+      - |
+        echo "[grampsweb] Ensuring admin user exists ..."
+        python3 << 'PYEOF' 2>&1 | grep -v Gtk
+        from gramps_webapi.app import create_app
+        from gramps_webapi.auth import add_user, get_number_users, ROLE_OWNER
+        import os
+        email = os.environ.get('GRAMPSWEB_ADMIN_EMAIL', '')
+        pw = os.environ.get('GRAMPSWEB_ADMIN_PASSWORD', '')
+        if email and pw:
+            app = create_app()
+            with app.app_context():
+                if get_number_users() == 0:
+                    add_user(name='Admin', email=email, password=pw, role=ROLE_OWNER)
+                    print('[grampsweb] Admin user created')
+                else:
+                    print('[grampsweb] Users already exist, skipping')
+        else:
+            print('[grampsweb] No admin credentials configured, skipping')
+        PYEOF
+        exec gunicorn -w $${GUNICORN_NUM_WORKERS:-4} -b 0.0.0.0:5000 \
+          gramps_webapi.wsgi:app --timeout $${GUNICORN_TIMEOUT:-120} \
+          --limit-request-line 8190
     volumes:
       - gramps_data_dev:/app/data
     depends_on:
@@ -209,9 +234,9 @@ services:
 
 volumes:
   dbdata_dev:
+  gramps_data_dev:
   paperless_data_dev:
   paperless_media_dev:
   paperless_export_dev:
   paperless_consume_dev:
-  gramps_data_dev:
   ollama_data_dev:

compose.yml

@@ -193,15 +193,41 @@ services:
     ports:
       - "8090:5000"
     environment:
-      - GRAMPSWEB_SECRET_KEY=${GRAMPSWEB_SECRET_KEY}
-      - GRAMPSWEB_ADMIN_EMAIL=${GRAMPSWEB_ADMIN_EMAIL}
-      - GRAMPSWEB_ADMIN_PASSWORD=${GRAMPSWEB_ADMIN_PASSWORD}
+      - GRAMPSWEB_SECRET_KEY=${GRAMPSWEB_SECRET_KEY:-dev-grampsweb-secret-key-not-for-production}
+      - GRAMPSWEB_ADMIN_EMAIL=${GRAMPSWEB_ADMIN_EMAIL:-admin@localhost}
+      - GRAMPSWEB_ADMIN_PASSWORD=${GRAMPSWEB_ADMIN_PASSWORD:-gramps_dev_password}
       - GRAMPSWEB_TREE=${GRAMPSWEB_TREE:-Stiftung}
-      - GRAMPSWEB_BASE_URL=${GRAMPSWEB_BASE_URL:-/ahnenforschung}
+      - GRAMPSWEB_BASE_URL=${GRAMPSWEB_BASE_URL:-https://vhtv-stiftung.de/ahnenforschung}
       - GRAMPSWEB_CELERY_CONFIG__broker_url=redis://redis:6379/0
       - GRAMPSWEB_CELERY_CONFIG__result_backend=redis://redis:6379/0
       - GRAMPSWEB_RATELIMIT_STORAGE_URI=redis://redis:6379/1
       - GRAMPSWEB_NEW_DB_BACKEND=sqlite
+    command:
+      - sh
+      - -c
+      - |
+        # All subpath rewriting is handled by nginx sub_filter — no container patching needed.
+        echo "[grampsweb] Ensuring admin user exists ..."
+        python3 << 'PYEOF' 2>&1 | grep -v Gtk
+        from gramps_webapi.app import create_app
+        from gramps_webapi.auth import add_user, get_number_users, ROLE_OWNER
+        import os
+        email = os.environ.get('GRAMPSWEB_ADMIN_EMAIL', '')
+        pw = os.environ.get('GRAMPSWEB_ADMIN_PASSWORD', '')
+        if email and pw:
+            app = create_app()
+            with app.app_context():
+                if get_number_users() == 0:
+                    add_user(name='Admin', email=email, password=pw, role=ROLE_OWNER)
+                    print('[grampsweb] Admin user created')
+                else:
+                    print('[grampsweb] Users already exist, skipping')
+        else:
+            print('[grampsweb] No admin credentials configured, skipping')
+        PYEOF
+        exec gunicorn -w $${GUNICORN_NUM_WORKERS:-8} -b 0.0.0.0:5000 \
+          gramps_webapi.wsgi:app --timeout $${GUNICORN_TIMEOUT:-120} \
+          --limit-request-line 8190
     volumes:
       - gramps_data:/app/data
     depends_on:

deploy-production/docker-compose.prod.yml

@@ -128,6 +128,72 @@ services:
       - GRAMPSWEB_CELERY_CONFIG__result_backend=redis://redis:6379/0
       - GRAMPSWEB_RATELIMIT_STORAGE_URI=redis://redis:6379/1
       - GRAMPSWEB_NEW_DB_BACKEND=sqlite
+      - GRAMPSWEB_SUBPATH=${GRAMPSWEB_SUBPATH:-/ahnenforschung}
+    command:
+      - sh
+      - -c
+      - |
+        if [ -n "$$GRAMPSWEB_SUBPATH" ] && [ "$$GRAMPSWEB_SUBPATH" != "/" ]; then
+          SUBPATH="$$GRAMPSWEB_SUBPATH"
+          case "$$SUBPATH" in */) ;; *) SUBPATH="$${SUBPATH}/" ;; esac
+          echo "[grampsweb] Patching static files for subpath $$SUBPATH ..."
+          find / -name index.html -path "*/gramps*" -o -name index.html -path "*/static/*" 2>/dev/null | while read f; do
+            if grep -q '<base href="/">' "$$f" 2>/dev/null; then
+              sed -i "s|<base href=\"/\">|<base href=\"$$SUBPATH\">|g" "$$f"
+              echo "[grampsweb]   patched base href: $$f"
+            fi
+          done
+          for f in /app/static/*.js; do
+            if [ -f "$$f" ] && grep -q '/api/' "$$f" 2>/dev/null; then
+              sed -i "s|\"/api/|\"$${SUBPATH}api/|g" "$$f"
+              sed -i 's|`/api/|`'"$${SUBPATH}"'api/|g' "$$f"
+              sed -i "s|\"/lang/|\"$${SUBPATH}lang/|g" "$$f"
+              sed -i 's|`/lang/|`'"$${SUBPATH}"'lang/|g' "$$f"
+              sed -i "s|\"/fonts/|\"$${SUBPATH}fonts/|g" "$$f"
+              sed -i 's|`/fonts/|`'"$${SUBPATH}"'fonts/|g' "$$f"
+              sed -i "s|\"/assets/|\"$${SUBPATH}assets/|g" "$$f"
+              sed -i 's|`/assets/|`'"$${SUBPATH}"'assets/|g' "$$f"
+              sed -i "s|location\.href=\"/\"|location.href=\"$$SUBPATH\"|g" "$$f"
+              sed -i "s|document\.location\.href=\"/\"|document.location.href=\"$$SUBPATH\"|g" "$$f"
+              echo "[grampsweb]   patched JS paths: $$f"
+            fi
+          done
+          if [ -f /app/static/sw.js ]; then
+            sed -i "s|createHandlerBoundToURL(\"/index.html\")|createHandlerBoundToURL(\"$${SUBPATH}index.html\")|g" /app/static/sw.js
+            SUBPATH_BS=$$(echo "$$SUBPATH" | sed "s|/|\\\\\\\\/|g")
+            sed -i "s|\\^\\\\/api|\\^$${SUBPATH_BS}api|g" /app/static/sw.js
+            echo "[grampsweb]   patched sw.js navigation routes"
+          fi
+          find /app/static -name '*.css' 2>/dev/null | while read f; do
+            if grep -q '\.\./fonts/' "$$f" 2>/dev/null; then
+              sed -i "s|'../fonts/|'fonts/|g" "$$f"
+              sed -i "s|\"../fonts/|\"fonts/|g" "$$f"
+              echo "[grampsweb]   patched CSS font paths: $$f"
+            fi
+          done
+          echo "[grampsweb] Done."
+        fi
+        echo "[grampsweb] Ensuring admin user exists ..."
+        python3 << 'PYEOF' 2>&1 | grep -v Gtk
+        from gramps_webapi.app import create_app
+        from gramps_webapi.auth import add_user, get_number_users, ROLE_OWNER
+        import os
+        email = os.environ.get('GRAMPSWEB_ADMIN_EMAIL', '')
+        pw = os.environ.get('GRAMPSWEB_ADMIN_PASSWORD', '')
+        if email and pw:
+            app = create_app()
+            with app.app_context():
+                if get_number_users() == 0:
+                    add_user(name='Admin', email=email, password=pw, role=ROLE_OWNER)
+                    print('[grampsweb] Admin user created')
+                else:
+                    print('[grampsweb] Users already exist, skipping')
+        else:
+            print('[grampsweb] No admin credentials configured, skipping')
+        PYEOF
+        exec gunicorn -w $${GUNICORN_NUM_WORKERS:-8} -b 0.0.0.0:5000 \
+          gramps_webapi.wsgi:app --timeout $${GUNICORN_TIMEOUT:-120} \
+          --limit-request-line 8190
     volumes:
       - gramps_data:/app/data
     depends_on:

deploy-production/nginx.conf

@@ -83,6 +83,10 @@ server {
     }
 
     # GrampsWeb Ahnenforschung
+    # All path rewriting happens here via sub_filter — no container-side patching needed.
+    # GrampsWeb SPA uses Vaadin Router with absolute paths; the injected History API
+    # interceptor ensures pushState/replaceState calls get the /ahnenforschung/ prefix,
+    # while <base href> lets the router strip it back for route matching.
     location /ahnenforschung/ {
         proxy_pass http://127.0.0.1:8090/;
         proxy_set_header Host $host;
@@ -91,7 +95,41 @@ server {
         proxy_set_header X-Forwarded-Proto $scheme;
         proxy_set_header X-Script-Name /ahnenforschung;
 
-        # WebSocket support (GrampsWeb uses SSE/WS for real-time updates)
+        # Disable upstream compression so sub_filter can operate on response bodies
+        proxy_set_header Accept-Encoding "";
+
+        # Apply sub_filter to HTML, JS, and CSS responses
+        sub_filter_types text/html application/javascript text/css;
+        sub_filter_once off;
+
+        # HTML: set <base href> so the SPA router knows its prefix
+        sub_filter '<base href="/">' '<base href="/ahnenforschung/">';
+
+        # HTML: inject History API interceptor — ensures pushState/replaceState
+        # always include the /ahnenforschung/ prefix for correct SPA routing on reload
+        sub_filter '</head>' '<script>!function(){var p="/ahnenforschung",o=history.pushState,r=history.replaceState;function w(u){return"string"==typeof u&&"/"===u[0]&&0!==u.indexOf(p)?p+u:u}history.pushState=function(s,t,u){return o.call(this,s,t,w(u))},history.replaceState=function(s,t,u){return r.call(this,s,t,w(u))}}();</script></head>';
+
+        # JS: rewrite hardcoded absolute API/resource paths
+        sub_filter '"/api/' '"/ahnenforschung/api/';
+        sub_filter '`/api/' '`/ahnenforschung/api/';
+        sub_filter '"/lang/' '"/ahnenforschung/lang/';
+        sub_filter '`/lang/' '`/ahnenforschung/lang/';
+        sub_filter '"/fonts/' '"/ahnenforschung/fonts/';
+        sub_filter '`/fonts/' '`/ahnenforschung/fonts/';
+        sub_filter '"/assets/' '"/ahnenforschung/assets/';
+        sub_filter '`/assets/' '`/ahnenforschung/assets/';
+
+        # JS: rewrite root redirects
+        sub_filter 'location.href="/"' 'location.href="/ahnenforschung/"';
+        sub_filter 'document.location.href="/"' 'document.location.href="/ahnenforschung/"';
+
+        # JS: service worker route handling
+        sub_filter 'createHandlerBoundToURL("/index.html")' 'createHandlerBoundToURL("/ahnenforschung/index.html")';
+
+        # CSS: fix relative font paths (served from subpath, ../fonts/ won't resolve)
+        sub_filter '../fonts/' 'fonts/';
+
+        # WebSocket support
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;
         proxy_set_header Connection "upgrade";

deploy.sh

@@ -135,6 +135,23 @@ echo ""
 echo "--- Collecting static files ---"
 docker compose -f "$COMPOSE_FILE" exec -T web python manage.py collectstatic --noinput
 
+echo ""
+echo "--- Updating nginx config ---"
+NGINX_CONF="$PROD_DIR/deploy-production/nginx.conf"
+NGINX_DEST="/etc/nginx/sites-enabled/stiftung"
+if [[ -f "$NGINX_CONF" ]]; then
+    if ! diff -q "$NGINX_CONF" "$NGINX_DEST" &>/dev/null; then
+        echo "Nginx config changed — updating and reloading"
+        sudo cp "$NGINX_CONF" "$NGINX_DEST"
+        sudo nginx -t && sudo systemctl reload nginx
+        echo "Nginx reloaded"
+    else
+        echo "Nginx config unchanged — skipping"
+    fi
+else
+    echo "WARNUNG: $NGINX_CONF nicht gefunden — nginx nicht aktualisiert"
+fi
+
 echo ""
 echo "--- Service status ---"
 docker compose -f "$COMPOSE_FILE" ps

env-template.txt

@@ -64,6 +64,7 @@ GRAMPSWEB_SECRET_KEY=your-grampsweb-secret-key-here
 GRAMPSWEB_ADMIN_EMAIL=admin@vhtv-stiftung.de
 GRAMPSWEB_ADMIN_PASSWORD=your-grampsweb-admin-password-here
 GRAMPSWEB_TREE=Stiftung
-GRAMPSWEB_BASE_URL=/ahnenforschung
+# Full external URL including subpath (used by GrampsWeb for email links, OIDC, etc.)
+GRAMPSWEB_BASE_URL=https://vhtv-stiftung.de/ahnenforschung