Why Apache Superset needs a reverse proxy with TLS in production
A reverse proxy with TLS is the normal way to give users browser access to Apache Superset over HTTPS on a shared domain. Superset itself is an application server that listens on an internal port, so the proxy layer is where you terminate encryption, present a stable hostname, apply security headers and route requests to the right place. Without it, users either reach an unencrypted port directly or your team exposes the application server in a way the rest of your network policy does not expect. The decision is rarely whether to use a proxy, but which one (NGINX, Traefik or a cloud load balancer) and how much of the request path it owns.
The routing question is larger than a single web endpoint. The architecture documentation lists four components: the Flask and React application, a metadata database, an optional caching layer, and optional Celery worker and beat processes. It also states that alerts and reports, async queries and dashboard thumbnails require the caching layer and worker components, and that most installations use Redis and Celery for them. That means the proxy may need to carry WebSocket traffic for async query results, while report workers and other internal callers may need plain HTTP paths that never pass through the public listener. Before you write any proxy rule, list which of these features you plan to enable, because each one adds a traffic pattern the proxy must handle.
Teams need this work as soon as Superset serves more than a single engineer's laptop: when a shared domain or path is required, when users sign in through an identity provider that expects an HTTPS callback, or when security review asks for encryption in transit. Confirm with your platform team which certificate authority, DNS names and load balancer product you will use, and whether your environment requires mutual TLS between the proxy and the application. Also confirm the Superset version you will run, since proxy-related configuration is read from the Superset configuration documentation for that release.
Which proxy and TLS options fit which environment
This table compares NGINX, Traefik and a cloud load balancer, and TLS termination at the proxy against re-encryption to Superset. Read each row against your hosting model, then confirm the exact keys such as ENABLE_PROXY_FIX in the Superset configuration documentation for the version you run.
| Option | What it does for Superset | Trade-off | When it fits |
|---|---|---|---|
| NGINX on your own host or VM | Terminates TLS, forwards requests to Gunicorn, and can route WebSocket upgrades for async query traffic | You own certificate renewal, header configuration and the upgrade path for the proxy itself | Self-managed VMs or bare metal where your team already operates NGINX |
| Traefik as ingress or container proxy | Discovers Superset containers from labels or Kubernetes resources and manages TLS certificates automatically | Routing and middleware are defined in labels or CRDs, so config review takes more care | Docker Compose or Kubernetes stacks already fronted by Traefik |
| Cloud load balancer with managed certificates | Terminates TLS at the cloud edge and handles health checks and certificate renewal as a managed service | Header and WebSocket behavior depends on the provider, so confirm forwarded headers and idle timeouts | Superset running in a cloud account where the platform team standardizes on managed load balancers |
| TLS terminated at the proxy, plain HTTP to Superset | Keeps certificate handling in one place and gives Superset the original scheme and client address through forwarded headers | Traffic between proxy and Superset is unencrypted, so the private network must be controlled | Single host or private subnet with no policy requiring encryption inside the network |
| TLS re-encrypted from proxy to Superset | Encrypts the hop between proxy and application as well as the client connection | Adds certificate management for internal endpoints and more failure points during renewal | Regulated environments or shared networks where internal traffic must be encrypted |
| ENABLE_PROXY_FIX | Tells Superset to read forwarded headers such as scheme, host and client address from the proxy | If enabled without a trusted proxy in front, clients can spoof these headers, so only enable it behind a controlled proxy | Any deployment where a proxy sits in front of Superset; confirm the flag and its behavior for your version |
| Health checks and internal HTTP for report workers | Gives the load balancer a stable endpoint and lets Celery workers reach Superset over an internal address for reports | Workers that call the public URL depend on DNS, proxy rules and certificate trust working from inside the network | Deployments with alerts, reports or thumbnails enabled; confirm the worker's web URL setting in your configuration |
Setup sequence for the proxy, headers and health checks
This sequence takes Superset from a direct listener to a proxied deployment where TLS terminates at the edge, forwarded headers are trusted only from the proxy, and WebSocket, health check and report worker paths are each verified. The result is a configuration your team can test step by step and roll back in order.
Confirm the application root and listener
Before touching the proxy, record the URL path Superset will be served under, the internal address and port the application listens on, and whether the proxy forwards the original path unchanged. Someone on the platform team should write these values into the change record, and the application should answer on the internal address with the path it will use publicly. Done means a direct request to the internal listener returns the Superset login page, and you have noted any path prefix separately if you plan to serve Superset under a sub-path. For a sub-path, follow the separate page on serving Superset under a URL path prefix.
Set ENABLE_PROXY_FIX and trust only the proxy
In the Superset configuration, set ENABLE_PROXY_FIX so the application reads forwarded scheme, host and client address headers from the proxy. Confirm the proxy overwrites these headers rather than passing client-supplied values through, and make sure the application port is reachable only from the proxy, because a client that can reach the application directly can forge them. Verify by sending a request through the proxy and checking the application log or a test view: the scheme should show https and the host should match the public name. If the values still show http or an internal host name, the forwarded headers are not reaching the application or the setting is not loaded.
Terminate TLS and add HSTS at the edge
Install the certificate and private key on NGINX, Traefik or the cloud load balancer, and configure the listener for HTTPS only. Add a Strict-Transport-Security response header at the edge, starting with a modest max-age and only after you have confirmed the whole hostname works over HTTPS, because browsers cache the policy. Your security team should confirm the certificate chain, the protocol versions allowed by the edge, and whether the header also applies to subdomains. Verify with an external TLS scan from a host outside your network and a header check showing the policy on the login page. Plain HTTP requests should redirect to HTTPS without reaching Superset.
Route WebSocket traffic for async queries
Async queries and some live features use WebSocket connections, so the proxy must upgrade those requests and keep the connection open long enough for queries to finish. Add the upgrade headers for the WebSocket path, set read and send timeouts that your longest expected query can outlast, and confirm the proxy does not buffer the stream. Ask the Superset team which WebSocket service and path your release uses, since the path depends on the version and whether async queries are enabled. Verify by running a query in the UI with async execution turned on and confirming that results arrive without a reconnect loop in the browser developer console.
Expose a health check for the load balancer
Point the load balancer or proxy health check at an endpoint that Superset serves without requiring a logged-in session, and keep it on the internal network path. Choose a check that tests the application process and avoid one that runs a warehouse query on every probe, since that adds load to your analytics databases. Set the expected response and the interval with your platform team, and document which metadata database and cache checks the endpoint does or does not cover. Verify by stopping the application on one node in a test environment and confirming the balancer removes it from rotation.
Keep report workers on an internal HTTP path
Scheduled reports and alerts fetch dashboard pages through Superset to render screenshots, so the worker needs a route to the web application that does not depend on the public proxy. Configure the internal address the worker uses for these requests, and make sure it uses HTTP inside your network with the correct host header so the application accepts it. Confirm that the worker does not need to traverse the public TLS endpoint, and review which network path your Playwright or Chromium setup uses. Verify by sending a test report on a sample dashboard and checking that the rendered image and delivery both succeed when the public edge is blocked from the worker host.
Test the full path and document the rollback
Run one end-to-end check that covers login, a dashboard load, an async query, a health probe and a scheduled report, using the public hostname. Record the proxy and application versions, the header and timeout settings, and the certificate expiry date in your runbook. Keep the previous proxy configuration available so you can restore it if a later change breaks WebSocket or header handling. Done means every check passes from a client outside the internal network and the runbook lists who owns the certificate renewal and proxy changes.
How WebSocket routing and internal HTTP for report workers change the design
The proxy design has to account for two traffic patterns that a plain web front end does not have. Async queries and alerts or reports depend on the caching layer and Celery worker components, so a proxy that handles only ordinary page requests will break part of Superset without any visible error on the login page. Confirm that your proxy passes the Upgrade and Connection headers for WebSocket connections on the paths Superset uses for async query results, and that the connection timeout is longer than a typical query. Ask your platform team to test this on the staging proxy before any user depends on it, because a misrouted socket usually shows up as a spinner that never resolves.
The second pattern is callback traffic from the workers. When a report worker renders a dashboard thumbnail or a chart screenshot, it loads Superset through a URL, and that URL is set by the WEBDRIVER_BASE_URL setting and related configuration. If it points at the public hostname, the worker must leave your network, pass through the proxy, and come back in, which adds a dependency on external DNS, certificates and firewall rules for internal jobs. The common alternative is a split design: users reach Superset through the public hostname and the workers reach the web container over an internal address. That split is cleaner for report reliability, but it means the internal path must bypass TLS termination and still be authorized, and the two paths can drift apart if their settings are changed separately.
Decide between a single public path and a split internal path based on who can reach the worker network and how much you trust the internal segment. Then test both paths explicitly: a WebSocket-driven async query from a browser, a scheduled report that produces a screenshot, and a failed upstream certificate to confirm that the internal path does not fail silently. Record the result of each test against the configuration version you deploy, because the Superset architecture documentation at Apache Superset architecture describes which components each feature needs, and your proxy rules should match that list.
Security decisions at the proxy edge
The proxy is the first place Superset's TLS, forwarded headers and exposure get decided, so most of the risk sits there. The cards below cover the choices that change how Superset behaves for users and attackers, and the checks to run before go-live.
Certificate management and renewal
Decide who issues, stores and renews the certificate for the Superset hostname before launch, and where the private key lives. Expired certificates are a common cause of outages for internal BI tools that nobody watches closely. Confirm that renewal is automated, that the proxy reloads without dropping sessions, and that alerts fire before expiry. Check that the certificate chain is complete for the clients your analysts actually use.
HSTS scope and preload risk
The Strict-Transport-Security header tells browsers to use HTTPS for a host for a set period, and the includeSubDomains and preload options extend that to every subdomain. Set a short max-age while you test, and only enable subdomain coverage if every subdomain under that name serves HTTPS. Preload submission is hard to reverse, so confirm with your security team before adding it. Superset's own headers are configured in its settings, so agree which layer owns this header.
Trusted proxy addresses for forwarded headers
Superset relies on forwarded headers to know the original scheme, host and client address when ENABLE_PROXY_FIX is turned on. If the application trusts headers from any source, a client that reaches it directly can spoof them. Limit trust to the exact address of your proxy or load balancer, and confirm how many proxy hops sit in front of the app. Verify the behavior with a request that sends forged headers from outside the proxy path.
Restricting direct access to the app port
Superset's application server should accept connections only from the proxy, not from user networks or the open internet. Bind the application to a private interface or place it on a network segment that only the proxy can reach, and block the application port at the host and cloud firewall. Test this by connecting directly to the application port from a workstation network. Direct access would bypass TLS, HSTS and any rate limits you set at the edge.
Logging and rate limits at the edge
The proxy sees every request before Superset does, so its access logs are often the first record of a login attempt or unusual export pattern. Decide what to log, where logs go and how long they are kept, and make sure client addresses are captured correctly once forwarded headers are trusted. Rate limits on the login path slow credential guessing, but set them so analysts working through dashboards are not blocked. Confirm these settings with your monitoring and retention policies.
Questions teams ask before running Superset behind a proxy
What does it cost to put Superset behind a reverse proxy with TLS?
The cost is mostly the time of the people doing the work, plus any load balancer or certificate service you buy from your cloud or CA. Proxy configuration itself is not a large software cost because the Apache License 2.0 applies to Superset and the project has no paid edition. The main drivers are how many entry points you expose, whether you use NGINX, Traefik or a cloud load balancer, how many environments need matching routing, and whether WebSocket routing for async queries and internal HTTP for report workers must be verified. Ask any partner for a written scope that lists each environment, each routing path and each verification step, so the quote can be compared against your own team's effort.
How long does a typical proxy setup for Superset take?
No fixed duration applies because it depends on your existing edge stack, how many domains and environments are involved, and how quickly DNS and certificates can be issued inside your organization. Teams that already run NGINX, Traefik or a cloud load balancer with automated certificates usually need less time than teams building the edge from scratch. Confirm the timeline in writing with your partner or internal platform team, and make sure it includes staging validation, the health check and HSTS rollout, and a check that async queries and report thumbnails still work through the proxy before production cutover.
What does our internal team need to provide before the work starts?
Three groups of inputs are needed before routing can be configured:
- DNS records for the public hostname and a decision on the internal name Superset uses
- Certificates, or access to your certificate authority or cloud certificate service, plus the chain and renewal process
- Network access between the proxy, the Superset web servers, the metadata database, Redis and any Celery workers, and a staging environment that mirrors production routing
You should also name an owner who can approve firewall changes and a person who can confirm the SECRET_KEY and session settings for each environment.
Can our team set up the reverse proxy ourselves using the Superset documentation?
Yes, a team with proxy experience can often do it internally, because the Superset configuration documentation explains the settings that matter, including ENABLE_PROXY_FIX. The harder parts are the ones that cause quiet failures: forwarded headers that Superset trusts, WebSocket upgrades for async queries, internal HTTP paths for report workers, and HSTS applied only after TLS is verified end to end. Check whether your team has someone who has run these routes before, and whether they can test with real users and reports in staging. A partner can take that work under a written scope if your team lacks the time or the test coverage.
What should we check on each Superset upgrade when a proxy sits in front of it?
Every upgrade should be treated as a change to the whole request path, not only to Superset. The upgrade guide says to back up the metadata database, run superset db upgrade and superset init, test in staging first, and read UPDATING.md for breaking changes between versions. Once the proxy is in place, add checks for the health endpoint, forwarded headers, WebSocket routing for async queries, report delivery through the internal HTTP path and the HSTS header. If you move from the Helm chart to the Apache Superset Kubernetes Operator, which is in alpha, your proxy or ingress configuration may also need to change, so confirm that path before you commit.
Which security settings must be right before Superset goes live behind TLS?
Start with a SECRET_KEY set by you, because Superset will not start without one from version 2.1.0 onward. Then confirm that the proxy terminates TLS with a current certificate, forwards the client scheme and host correctly, and only sends HSTS once HTTPS works for every hostname covered by the header. Limit which network paths can reach the Superset web servers directly, and make sure the metadata database is not exposed through the proxy. Review these items with your security team, and if you need evidence for an assessment, document each setting and its test result rather than relying on memory.
Does DeployOpen issue a certificate or audit report for our proxy setup?
No. DeployOpen plans, implements, hardens, documents and tests self-hosted platforms in your own infrastructure, and prepares systems and evidence for compliance assessments. Independent auditors and certification bodies issue audit reports, attestations and certifications. For certificates, your organization or your certificate authority issues them, and DeployOpen can configure the proxy to use them. Ask any partner to state in the written scope which evidence will be delivered and which items remain the responsibility of your team or your auditor.
Keeping proxy settings stable across Superset upgrades
Proxy configuration should be versioned alongside Superset's own configuration and treated as part of every upgrade, not as infrastructure that is set once and forgotten. The NGINX, Traefik or cloud load balancer rules, the ENABLE_PROXY_FIX setting, the TLS certificate chain, and the HSTS header value should live in Git with the same review process as superset_config.py. Before any production upgrade, rehearse the change in staging with a copy of production-like proxy rules. Follow the sequence in the Superset upgrade guide: back up the metadata database, run superset db upgrade and superset init, and read UPDATING.md for breaking changes between your current and target versions. A breaking change that affects request handling, such as altered header expectations, can look like a proxy fault, so record which version of the proxy config was tested with which Superset release.
After each upgrade, test the behaviors that the proxy carries, not only whether the login page loads. Confirm that the redirect scheme and host are correct so that links, OAuth callbacks and CSRF checks use https and the public hostname. Confirm that HSTS is still sent on responses and that the value matches your policy. For WebSockets, run an async query from a dashboard and confirm the connection upgrades and the result returns, because a dropped Upgrade or Connection header usually shows up as a query that hangs. Check the health check endpoint your load balancer polls, and confirm the internal path used by report workers still reaches the web service without passing through the public TLS listener, if your design uses that route.
Write these checks as a runbook with expected results, and have someone other than the upgrade engineer run it in staging. Ask your partner or vendor to confirm which proxy and header behavior changed in the target release, and which items in UPDATING.md touch the web layer. Agree on a rollback point: a tested database backup plus the previous proxy configuration version in Git. Confirm the exact health check path and expected response for your Superset version against the architecture documentation and your own staging results, since the components that must answer health checks can differ by deployment method.
How DeployOpen scopes and delivers a proxy and TLS setup
DeployOpen plans, builds, documents and supports the proxy and TLS layer in front of Superset inside your own infrastructure, whether that is NGINX, Traefik or a cloud load balancer. Each engagement starts from a written scope that names the routes, certificates, headers and worker paths your environment needs. Work is fixed-scope, with ongoing support available as a retainer.
How we scope
- Inventory your hostnames, certificate authority, TLS termination point and existing load balancer or ingress.
- Confirm which features need WebSocket routing, including async queries, and which need internal HTTP paths for report workers.
- Agree in writing which headers, HSTS settings and health check endpoints are in scope and who owns each decision.
How we build
- Configure the proxy and set ENABLE_PROXY_FIX to match the forwarded headers your proxy actually sends.
- Verify the Superset application root and external URL so redirects, cookies and generated links resolve to the public hostname.
- Test login, dashboard rendering, async query updates and report generation through the proxy in a staging environment first.
How we hand over
- Deliver versioned proxy configuration, certificate renewal steps and a written map of which paths reach Superset and which stay internal.
- Document the verification checks run during testing, with the results and the commands used to repeat them.
- Walk your platform and security teams through the runbook so they can change the setup without guesswork.
How we support
- Review proxy and TLS changes when you upgrade Superset, checking the upgrade notes for any routing or configuration changes.
- Support certificate renewal, proxy version updates and changes to health check or HSTS settings under a retainer.
- Re-run the agreed test set after changes so regressions in login, async queries or reports surface before users find them.
