feat: Allow superset to be deployed under a prefixed URL (#30134)

Co-authored-by: Kamil Gabryjelski <[email protected]>

Author: martyngigg

.github/workflows/bashlib.sh

@@ -145,14 +145,20 @@ cypress-install() {
 
 cypress-run-all() {
   local USE_DASHBOARD=$1
+  local APP_ROOT=$2
   cd "$GITHUB_WORKSPACE/superset-frontend/cypress-base"
 
   # Start Flask and run it in background
   # --no-debugger means disable the interactive debugger on the 500 page
   # so errors can print to stderr.
   local flasklog="${HOME}/flask.log"
   local port=8081
-  export CYPRESS_BASE_URL="http://localhost:${port}"
+  CYPRESS_BASE_URL="http://localhost:${port}"
+  if [ -n "$APP_ROOT" ]; then
+    export SUPERSET_APP_ROOT=$APP_ROOT
+    CYPRESS_BASE_URL=${CYPRESS_BASE_URL}${APP_ROOT}
+  fi
+  export CYPRESS_BASE_URL
 
   nohup flask run --no-debugger -p $port >"$flasklog" 2>&1 </dev/null &
   local flaskProcessId=$!

.github/workflows/superset-e2e.yml

@@ -42,6 +42,7 @@ jobs:
       matrix:
         parallel_id: [0, 1, 2, 3, 4, 5]
         browser: ["chrome"]
+        app_root: ["", "/app/prefix"]
     env:
       SUPERSET_ENV: development
       SUPERSET_CONFIG: tests.integration_tests.superset_test_config
@@ -135,7 +136,7 @@ jobs:
           CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}
           NODE_OPTIONS: "--max-old-space-size=4096"
         with:
-          run: cypress-run-all ${{ env.USE_DASHBOARD }}
+          run: cypress-run-all ${{ env.USE_DASHBOARD }} ${{ matrix.app_root }}
       - name: Upload Artifacts
         uses: actions/upload-artifact@v4
         if: failure()

Dockerfile

@@ -208,7 +208,7 @@ RUN rm superset/translations/*/*/*.po
 COPY --from=superset-node /app/superset/translations superset/translations
 COPY --from=python-translation-compiler /app/translations_mo superset/translations
 
-HEALTHCHECK CMD curl -f "http://localhost:${SUPERSET_PORT}/health"
+HEALTHCHECK CMD /app/docker/docker-healthcheck.sh
 CMD ["/app/docker/entrypoints/run-server.sh"]
 EXPOSE ${SUPERSET_PORT}
 

docker-compose.yml

@@ -29,7 +29,6 @@ x-superset-volumes: &superset-volumes
   - ./superset-frontend:/app/superset-frontend
   - superset_home:/app/superset_home
   - ./tests:/app/tests
-
 x-common-build: &common-build
   context: .
   target: ${SUPERSET_BUILD_TARGET:-dev} # can use `dev` (default) or `lean`
@@ -43,6 +42,11 @@ x-common-build: &common-build
 
 services:
   nginx:
+    env_file:
+      - path: docker/.env # default
+        required: true
+      - path: docker/.env-local # optional override
+        required: false
     image: nginx:latest
     container_name: superset_nginx
     restart: unless-stopped
@@ -52,6 +56,8 @@ services:
       - "host.docker.internal:host-gateway"
     volumes:
       - ./docker/nginx/nginx.conf:/etc/nginx/nginx.conf:ro
+      - ./docker/nginx/templates:/etc/nginx/templates:ro
+
   redis:
     image: redis:7
     container_name: superset_cache

docker/.env

@@ -54,6 +54,7 @@ REDIS_HOST=redis
 REDIS_PORT=6379
 
 FLASK_DEBUG=true
+SUPERSET_APP_ROOT="/"
 SUPERSET_ENV=development
 SUPERSET_LOAD_EXAMPLES=yes
 CYPRESS_CONFIG=false

docker/docker-healthcheck.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+curl -f "http://localhost:${SUPERSET_PORT}/${SUPERSET_APP_ROOT/\//}/health" || exit 1

docker/nginx/nginx.conf

@@ -90,44 +90,5 @@ http {
 
     client_max_body_size 10m;
 
-    upstream superset_app {
-        server host.docker.internal:8088;
-        keepalive 100;
-    }
-
-    upstream superset_websocket {
-        server host.docker.internal:8080;
-        keepalive 100;
-    }
-
-    server {
-        listen 80 default_server;
-        server_name  _;
-
-        location /ws {
-            proxy_pass http://superset_websocket;
-            proxy_http_version 1.1;
-            proxy_set_header Upgrade $http_upgrade;
-            proxy_set_header Connection "Upgrade";
-            proxy_set_header Host $host;
-        }
-
-        location /static {
-            proxy_pass http://host.docker.internal:9000;  # Proxy to superset-node
-            proxy_http_version 1.1;
-            proxy_set_header Host $host;
-        }
-
-        location / {
-            proxy_pass http://superset_app;
-            proxy_set_header    Host                $host;
-            proxy_set_header    X-Real-IP           $remote_addr;
-            proxy_set_header    X-Forwarded-For     $remote_addr;
-            proxy_set_header    X-Forwarded-Host    $host;
-            proxy_set_header    X-Forwarded-Proto   $scheme;
-            proxy_http_version 1.1;
-            port_in_redirect off;
-            proxy_connect_timeout 300;
-        }
-    }
+    include /etc/nginx/conf.d/superset.conf;
 }

docker/nginx/templates/superset.conf.template

@@ -0,0 +1,57 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+upstream superset_app {
+    server host.docker.internal:8088;
+    keepalive 100;
+}
+
+upstream superset_websocket {
+    server host.docker.internal:8080;
+    keepalive 100;
+}
+
+server {
+    listen 80 default_server;
+    server_name  _;
+
+    location /ws {
+        proxy_pass http://superset_websocket;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "Upgrade";
+        proxy_set_header Host $host;
+    }
+
+    location ${SUPERSET_APP_ROOT}/static {
+        proxy_pass http://host.docker.internal:9000;  # Proxy to superset-node
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+    }
+
+    location ${SUPERSET_APP_ROOT} {
+        proxy_pass http://superset_app;
+        proxy_set_header Host $http_host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_http_version 1.1;
+        port_in_redirect off;
+        proxy_connect_timeout 300;
+    }
+
+}

docker/pythonpath_dev/superset_config.py

@@ -71,6 +71,7 @@
     "CACHE_REDIS_DB": REDIS_RESULTS_DB,
 }
 DATA_CACHE_CONFIG = CACHE_CONFIG
+THUMBNAIL_CACHE_CONFIG = CACHE_CONFIG
 
 
 class CeleryConfig:
@@ -100,9 +101,11 @@ class CeleryConfig:
 
 FEATURE_FLAGS = {"ALERT_REPORTS": True}
 ALERT_REPORTS_NOTIFICATION_DRY_RUN = True
-WEBDRIVER_BASEURL = "http://superset:8088/"  # When using docker compose baseurl should be http://superset_app:8088/  # noqa: E501
+WEBDRIVER_BASEURL = f"http://superset_app{os.environ.get('SUPERSET_APP_ROOT', '/')}/"  # When using docker compose baseurl should be http://superset_nginx{ENV{BASEPATH}}/  # noqa: E501
 # The base URL for the email report hyperlinks.
-WEBDRIVER_BASEURL_USER_FRIENDLY = WEBDRIVER_BASEURL
+WEBDRIVER_BASEURL_USER_FRIENDLY = (
+    f"http://localhost:8888/{os.environ.get('SUPERSET_APP_ROOT', '/')}/"
+)
 SQLLAB_CTAS_NO_LIMIT = True
 
 log_level_text = os.getenv("SUPERSET_LOG_LEVEL", "INFO")

docs/docs/configuration/configuring-superset.mdx

@@ -215,6 +215,45 @@ In case the reverse proxy is used for providing SSL encryption, an explicit defi
 RequestHeader set X-Forwarded-Proto "https"
 ```
 
+## Configuring the application root
+
+*Please be advised that this feature is in BETA.*
+
+Superset supports running the application under a non-root path. The root path
+prefix can be specified in one of two ways:
+
+- Setting the `SUPERSET_APP_ROOT` environment variable to the desired prefix.
+- Customizing the [Flask entrypoint](https://github.com/apache/superset/blob/master/superset/app.py#L29)
+  by passing the `superset_app_root` variable.
+
+Note, the prefix should start with a `/`.
+
+### Customizing the Flask entrypoint
+
+To configure a prefix, e.g `/analytics`, pass the `superset_app_root` argument to
+`create_app` when calling flask run either through the `FLASK_APP`
+environment variable:
+
+```sh
+FLASK_APP="superset:create_app(superset_app_root='/analytics')"
+```
+
+or as part of the `--app` argument to `flask run`:
+
+```sh
+flask --app "superset.app:create_app(superset_app_root='/analytics')"
+```
+
+### Docker builds
+
+The [docker compose](/docs/installation/docker-compose#configuring-further) developer
+configuration includes an additional environmental variable,
+[`SUPERSET_APP_ROOT`](https://github.com/apache/superset/blob/master/docker/.env),
+to simplify the process of setting up a non-default root path across the services.
+
+In `docker/.env-local` set `SUPERSET_APP_ROOT` to the desired prefix and then bring the
+services up with `docker compose up --detach`.
+
 ## Custom OAuth2 Configuration
 
 Superset is built on Flask-AppBuilder (FAB), which supports many providers out of the box