Serve Apache Superset under a URL path prefix

Why teams serve Apache Superset under a URL path prefix

A URL path prefix lets Superset live at a path such as /analytics on a domain your organization already uses for other internal tools, so users reach it without a separate hostname. The change is worth the added configuration when several internal applications share one domain, when your security team wants one entry point and one certificate for internal sites, or when a reverse proxy already routes by path. If Superset can have its own hostname, that is usually the simpler route, and the prefix adds a layer every upgrade and proxy change must respect.

The prefix is not only a proxy rule. Superset must also generate its links, static asset paths and API calls under that prefix, so the application root setting in superset_config.py and the matching path rules in your proxy have to agree. The Superset configuration documentation describes this feature as a beta. Confirm the exact setting name, its default and its behavior against the release you run before you plan around it, because beta settings can change between releases. Check the Superset configuration documentation for the release in use.

Before committing, ask your platform team to test three things in staging: that login redirects, dashboard links and chart exports all keep the prefix, that the Swagger UI and API paths resolve under it, and that assets load when the proxy strips or keeps the prefix. Record which behaviors were verified on which release, because a prefix that works today may need retesting after each upgrade.

Which path prefix settings fit your proxy layout

This table compares three ways to serve Superset under a path such as /analytics: setting the application root in superset_config.py, setting it through a Docker environment variable, or stripping the prefix at the proxy. Read each row against your proxy layout, since the right choice depends on whether Superset must know its own public path. Confirm the exact configuration key and environment variable names in the Superset configuration documentation for the release you run.

Option	When it fits	What it changes and what must match at the proxy
Application root in superset_config.py	Packages or VMs where you manage a config file and want the prefix recorded with other settings	Superset generates links, redirects and static asset URLs with the prefix. The proxy must forward the full path unchanged, and the prefix in the config must match the proxy location exactly.
Application root through a Docker environment variable	Container deployments where settings come from the environment and config files are mounted or kept minimal	Same effect on generated URLs as the config file setting. Set the variable on the Superset container, not only on the proxy, and confirm the variable name for your release.
Prefix stripped at the reverse proxy or load balancer	Shared domains where the proxy already rewrites paths and Superset should believe it runs at the root	Superset generates root-relative links that the browser then resolves against the public domain, which breaks when assets or redirects expect /analytics. Usually a poor fit unless you test every redirect and asset path.
Choosing between the first two options	Teams that run one configuration across several environments	Keep the prefix in one place only. Mixing a config file value with an environment variable can produce conflicting URLs, so check which value wins in your release.
Proxy location and trailing slashes	Any setup with a path prefix	The proxy location, the application root and the trailing slash behavior must agree. Mismatches commonly show up as redirect loops, 404 errors on static files or login redirects to the wrong host.
Forwarded headers and TLS	Any setup behind TLS termination	Confirm how the proxy passes scheme, host and prefix headers, and whether Superset needs proxy fix settings to build correct external URLs. Test over HTTPS, since insecure links are a common symptom.
Swagger UI and API docs	Installations that expose the API documentation under the prefix	Check that the API documentation page and its assets load under the prefix. The Swagger UI behavior is part of the beta feature, so test it separately after every upgrade.
Verification before cutover	All options	Test login, dashboard embedding links, export downloads, static assets and the API docs at the public URL. Record the settings used so an upgrade review can compare them.

Setting the application root step by step

This sequence moves Superset from a root-path install to a working instance under a prefix such as /analytics on a shared domain. It ends with a login page, assets and redirects that keep the prefix, and a health check that answers through the proxy. Because the feature is documented as beta, run the sequence in staging before any production change.

Choose the prefix and check for collisions
The platform or web team picks a path such as /analytics and lists every route already served on the shared domain, including other applications, health paths and static asset paths. Confirm that no existing application or proxy rule claims the prefix or any path beneath it. Record the chosen prefix and the owning team in the change record. Done when the team holds a written list of routes checked and no overlap was found.
Set the application root in staging configuration
The Superset administrator sets the application root in the superset_config.py file for the staging environment, using the prefix chosen in the previous step. If you deploy with containers, set the matching Docker environment variable instead, and confirm its exact name in the configuration documentation for your Superset version. Keep the value identical in the config file and the container definition so the two sources cannot disagree. Done when staging shows one prefix value in every place it is set.
Configure the proxy to route the prefix
The network or platform team adds a rule in the reverse proxy or load balancer that forwards requests under the prefix to the Superset web process, and passes the original host and scheme headers. Write the rule using your proxy's documentation, and confirm whether the proxy should strip or keep the prefix for your Superset version. Align TLS and header settings with your existing proxy standards. Done when a request to the prefix reaches Superset in staging and no other application answers under it.
Restart the web process and workers
Restart the Superset web process so it loads the new configuration. If Celery workers and beat run in the same environment, restart them as well, since they read the same configuration file. Check whether alerts, reports and dashboard thumbnails build links or fetch pages through the application root, and confirm the expected behavior in the documentation for your version. Done when startup logs show no configuration errors and the process listens on its expected local address.
Load the login page under the prefix
Open the Superset login page through the prefixed URL in a browser that has no existing session. Confirm that the page renders with its styles and scripts, that the browser console reports no 404 errors for assets, and that signing in redirects back under the prefix rather than to the bare domain. Test with the authentication method your environment uses, such as local accounts or single sign-on. Done when a user can sign in and land on a page that still carries the prefix.
Check the health endpoint through the proxy
Call the Superset health endpoint through the proxy using the prefixed path, then call the web process directly on its local address for comparison. Confirm the health path for your version in the configuration documentation before you script the check. Add the same check to your monitoring so that a later proxy change is caught. Done when both calls return a successful response and the monitor reports the prefixed check as healthy.
Promote the verified setup to production
Run the full sequence in staging, then record the final configuration, proxy rule and rollback steps in the change record for review. Include a rollback plan that returns Superset to its previous root path, and test that rollback in staging first. Because the feature is documented as beta, review its stated limits for your version and decide in advance how you will handle any issue that appears after launch. Done when the change is approved, the rollback has been tested and the production change is scheduled.

Where the prefix is set in VM, container and Kubernetes installs

On a virtual machine, Superset runs as a Python process started from a virtual environment, so the prefix lives in the configuration file that the process loads at startup. In most installs that file is superset_config.py, and the application root setting is read when the web server process starts. Your reverse proxy must forward the prefix unchanged, and Superset must generate links that include it.

Config file location. Keep the setting in the superset_config.py file that your service unit or launch script loads, and confirm the exact key name in the configuration documentation for your version.
Process delivery. The value reaches Superset when Gunicorn or your WSGI server starts, so every change needs a service restart.
Upgrades. A package upgrade replaces Superset code but leaves your config file in place, so review the setting against the breaking change notes in UPDATING.md for the target version.
Proxy alignment. The proxy location block and the application root must match exactly, including how trailing slashes are handled.

Check the setting by loading the prefixed URL and confirming that static assets and login redirects also carry the prefix.

In a container install, the prefix is usually set through an environment variable passed to the container at run time, or through a configuration file mounted into the image. The image itself should stay unchanged so the same image runs in every environment. Confirm the exact variable name in the configuration documentation for your version before you write it into a Compose file or manifest.

Environment variable. Set it in the docker run command, the Compose environment block or your orchestrator's environment list, so the process reads it at container start.
Mounted config. If you mount superset_config.py, the mount path must match the path the image loads, and the file is read only at startup.
Image upgrades. A new image tag keeps your environment variables, but the release notes for that version should be checked for changed defaults before you promote it.
Restart behavior. Changing the variable requires recreating the container, because running processes keep the value they started with.

After startup, confirm in the container logs that the prefix is applied, then test the proxy route before you promote the image.

What Swagger UI and API paths do under a prefix

Under a URL path prefix, the API documentation page and the REST API paths both have to resolve through the prefix, and neither is guaranteed to do so just because the main login page loads. Start in the browser by opening the Swagger UI page at the prefixed address and confirming that it requests its OpenAPI specification from the prefixed location, not from the domain root. Check the browser's network panel for the specification request and for each API call the page makes. A page that renders but loads its specification from / or from a path the proxy does not forward will look broken only when someone tries an endpoint, so test an actual call rather than trusting the rendered page.

Scripts and embedded callers are the larger risk, because they fail silently or in ways that look like authentication errors. Inventory every client that calls the Superset REST API: notebooks, scheduled jobs, CI pipelines, BI connectors, portal integrations and any embedded dashboard code. For each one, confirm which base URL it uses and whether the base URL now includes the prefix. Do not assume that a client that worked before will work after a move, and do not assume that a change in one client applies to the others. Also confirm that login, token issuance and CSRF or session handling still complete through the prefix, since those calls are often the first to break.

Treat the exact behavior as release-specific and test it against the Superset version you plan to run, because the prefix feature is in beta and path handling for the documentation page and the API has changed between releases. Confirm the current status and any known limits in the Superset release notes and configuration documentation before you commit to a design. A workable test plan covers four groups: the UI (login, navigation, static assets, redirects after sign-in), the API documentation (specification load, a try-it-out call, and the download link for the specification), API clients (one authenticated read and one write from each class of caller, using the new base URL), and embedded or automated callers in a staging copy of the proxy configuration. Record the results per version so the same checks can be rerun at each upgrade.

Security risks of sharing a domain with Superset

Serving Superset under a path such as /analytics places it beside other applications on the same host name. That shared origin changes how cookies, redirects, TLS and routing behave, and each effect below needs a deliberate decision in the proxy and the Superset configuration.

Cookie scope and sessions

Browsers send cookies for a host to every path under it unless the cookie is scoped more narrowly. A session cookie set by another application on the same domain can reach Superset, and a Superset cookie can reach the neighbor. Check the cookie path, domain and SameSite attributes that Superset sets, and confirm that no other application on the domain sets a cookie with a conflicting name. Ask your team to document every cookie name in use.

Redirect and host header handling

Superset builds absolute URLs for login, OAuth callbacks and redirects from the request it receives. If the proxy forwards the wrong host, prefix or scheme, users can be sent to an address outside the intended path or to an internal name. Set the forwarded headers explicitly at the proxy, and test a logout, an OAuth sign-in and a direct visit to a deep link after changing the prefix.

TLS and HSTS placement

HSTS applies to the whole host, not just the Superset path, so a header set for analytics can affect every application on the domain. Decide which layer terminates TLS and which layer adds Strict-Transport-Security, and confirm that the header is not duplicated or contradicted by Superset and the proxy. Review the decision with the owners of the other applications before enabling it.

Path collisions and misrouting

Two applications that both claim a prefix, or a root path that falls through to the wrong upstream, can send a request to the wrong service. Superset static assets and API routes under the prefix must match the proxy rules exactly. Confirm that each path has one owner, that unmatched paths return an error rather than another application, and that a trailing slash or double slash does not change the route.

Pinned SECRET_KEY and session settings

Superset requires a user-specified SECRET_KEY, and changing it invalidates existing sessions and encrypted values unless a previous key is kept for rotation. Changing the prefix, the domain or the session settings during a move can look like a harmless edit but can force sign-outs or break decryption. Keep these values unchanged, store them in your secret manager, and record the approved values and any rotation steps in your runbook.

Proxy hardening as a shared control

The reverse proxy now enforces boundaries that Superset cannot see, including which paths are published, which headers are trusted and which upstreams a prefix may reach. Treat the proxy configuration as a security control with its own review, change history and tests, and align it with the hardening tasks for headers, roles and export controls. Ask who owns the shared domain and who approves changes to it.

Operating a prefixed Superset after go-live

The main day-two change is that the prefix becomes part of your release surface. Keep the proxy routing rules, the path prefix setting in superset_config.py, and the Docker environment variable that sets the application root in the same version-controlled repository, and change them in the same reviewed commit. A proxy rule that strips or adds /analytics and a Superset setting that disagrees with it will produce broken redirects, missing static assets or blank pages, and the failure often appears only after someone changes one side alone. Store the configuration in the same place your other environment overrides live so that a reviewer sees both halves of the routing contract at once.

Every Superset upgrade needs a prefix test added to the checklist. Before anything else, take a backup of the metadata database, then run the upgrade in staging first, as the project's upgrade guide describes, and run superset db upgrade and superset init as part of that rehearsal. Read the UPDATING.md breaking change notes for the target version and look specifically for entries that touch routing, static asset handling, the frontend build or the Swagger UI. After the staging upgrade, load the login page, a dashboard, a chart export and the API documentation through the public prefixed URL, and confirm that the browser requests static files under the prefix. Confirm with your own staging results whether the release notes for each target version change any of these behaviors, because this page does not list them.

Limits of the beta feature to confirm before rollout

The path prefix setup touches the UI, the API, extensions and the release you run, so each limit below needs a check in your own environment. Confirm each item with the project's documentation and test it in staging on the exact version you plan to deploy.

Beta status in the documentation

Confirm how the project labels the application root setting in the configuration documentation for your version. A beta label means the project has not committed to the behavior as stable, so a later release may change it. Record the wording you find, the version it applies to, and the date you checked, and keep that record with your change request. If the label is unclear or missing, ask the project in its community channels before you rely on the setting for a production URL.

UI coverage under a prefix

Ask which parts of the web interface the project tests under a path prefix. Login, dashboard lists, chart explore views, SQL Lab, settings pages and logout each build their own links, redirects and browser routes. In staging, walk through each area under the prefix, open a deep link directly, refresh the page, and confirm that every redirect keeps the prefix. Note any area that returns to the domain root.

API and Swagger UI behavior

Check that the REST API and the Swagger UI both resolve and call endpoints correctly under your prefix. The interactive documentation builds request URLs in the browser, so a base path mismatch can make try-it-out calls fail even when the API responds directly. Open the Swagger page under the prefix, run one read-only request from it, and compare the URL it calls with the URL you typed. Ask the project whether the Swagger UI is covered by the beta scope for your version.

Custom branding, embeds and plugins

Find out whether your branding, embedded dashboards or custom visualization plugins build absolute URLs that ignore the prefix. Search your templates, theme files and plugin code for hardcoded root paths, domain names and asset references. Embedding through the SDK depends on the host application's URLs as well, so test an embedded dashboard from a page on your product domain. Any absolute path found in custom code needs a fix before the prefix is used in production.

Release-specific behavior changes

Confirm that the release you pin still handles the prefix the way your test showed. Read the release notes for every version between your current and target release, because routing and configuration behavior can change in a minor release. Pre-release builds such as release candidates are listed on the GitHub releases page, and they should not carry a production URL. Repeat the prefix test after each upgrade, and keep the result with the upgrade record.

Static assets, fonts and map tiles

Verify that static files, fonts, locale files and map tile requests load under the prefix. Map charts usually call an external or internal tile server, and that address is set separately from the application root. Open a map chart and a page with custom fonts, then inspect the browser's network log for 404 responses or requests to the domain root. If your network blocks outside access, confirm that tile and font sources resolve from inside your network.

What does serving Superset under a prefix cost and take?

How much effort does serving Superset under a URL path prefix add?

For a single application, the core configuration change is small, but the effort grows with everything around it. The Superset side means setting the application root and checking that static assets, login redirects and links all resolve under the prefix. The larger effort sits in the proxy layer, where routing, TLS, headers and health checks must agree with that prefix. Ask any quote to break the work into the Superset configuration, the proxy changes, and the browser and API testing, so you can see where the hours go.

Can our own team set up a Superset path prefix without a partner?

Often yes, if your team already runs Superset behind a reverse proxy and can test changes in staging. The configuration itself is documented in the Superset configuration guide, and the Docker environment variable and Swagger UI behavior are straightforward to check once the prefix is set. A partner adds value when the prefix is one of several shared-domain changes at once, or when the team lacks someone who owns the proxy. Decide based on who owns the proxy and who will test the result.

What does the work need from our client team?

Plan for named owners for the reverse proxy or load balancer, the DNS and TLS certificates for the shared domain, and the Superset administrators who can approve a test plan. You will also need access to a staging environment that mirrors the production path, and someone who knows which other applications share the domain. Without these, the work stalls on approvals rather than configuration. A written scope should list each of these inputs and who provides them.

How long does testing a prefixed Superset take?

Testing duration depends on how many user paths you need to verify and how many integrations rely on the prefixed URLs. Plan separate passes for login and SSO redirects, dashboard and chart rendering, asynchronous queries, alerts and reports, and any embedded or API consumers. Ask a quote to state the test cases it covers and how many staging cycles it assumes. No duration is fixed by the software itself, so the estimate should come from your test inventory.

What drives the cost of a prefix setup up or down?

Four factors matter most. The first is proxy ownership: a team that already runs and documents the reverse proxy needs less work than one that must build it. The second is the number of applications on the shared domain, since each one adds routing and conflict checks. The third is embedding and API use, because each external caller must be retested under the new paths. The fourth is test coverage, which sets how many staging cycles and regression checks are needed. Ask the quote to price each factor separately.

Does serving Superset under a prefix change how upgrades work?

The prefix does not change the core upgrade method, but it adds checks to every upgrade. The Superset upgrade guide still asks you to back up the metadata database, run the database upgrade and init commands, test in staging first, and read UPDATING.md for breaking changes. After each upgrade, repeat your prefix tests, since proxy rules, static asset paths and embedded URLs can break even when the application itself starts. Ask whether the quote includes a repeatable test script for future upgrades.

What ongoing costs come after the prefix setup is done?

The recurring costs are proxy maintenance, certificate renewal, re-testing after Superset upgrades, and any change to other applications on the shared domain. These are usually small per cycle but continue for as long as the deployment runs. If you choose a retainer for support, ask what it covers for upgrade testing and proxy changes, and what response process applies. Ask for those terms in writing before work starts.

How DeployOpen scopes and delivers a prefixed Superset

DeployOpen plans, builds and hands over Superset at a path prefix inside infrastructure you control, starting from a written scope that names the prefix, proxy layout and identity setup. The work covers the application root settings, the build and proxy configuration, verification of static assets and the API under the prefix, and documented operations for your team.

How we scope

Engagements are fixed-scope, with the prefix, domain layout and proxy design agreed in writing before work starts.
The written scope names every component serving the prefix, including the proxy, Superset web tier and any report workers.
Scope lists which browser flows, embedded uses and integrations must work under the prefix and how each will be tested.

How we build

We set the application root and matching asset and API paths in configuration, then rebuild and verify the image or package.
Each prefixed route is tested in a staging copy, including login redirects, static assets, exports and async query endpoints.
Beta limits, including any Swagger UI behavior, are recorded as known issues with a workaround or an accepted risk.

How we hand over

Deliverables include the configuration files, proxy rules, a test checklist and a short runbook for changes under the prefix.
Your team receives a record of which settings were changed from defaults and why, so future upgrades can be reviewed.
Handover includes a walkthrough of the upgrade steps, including checking breaking changes in UPDATING.md before each version change.

How we support

Ongoing support, upgrades and continuous testing are available as retainers after handover.
Retained support can re-run the prefix test checklist after each Superset release or proxy change.
Confirm with DeployOpen the response expectations and upgrade coverage for your environment before signing a retainer.

Serving Apache Superset under a URL path prefix