When Apache Superset deck.gl maps need planning before rollout
Teams that want location-based charts in Superset usually start by picking a chart type and a base map. deck.gl charts draw large geospatial layers over a map background, so the map background is the first decision to settle. Since Superset 6.0.0, OpenStreetMap is the default deck.gl base map and needs no API key, which makes it the simplest starting point for a pilot. Mapbox remains available, but it requires a MAPBOX_API_KEY, which means an account, a key to manage and a usage relationship with a third party that your security and procurement teams will need to review.
Map tiles are a configuration decision, not a chart setting. Analysts cannot choose a tile provider inside a chart, so the choice belongs to whoever administers the deployment. Using a custom tile server means setting DECKGL_BASE_MAP, which replaces the defaults entirely. Once you do that, the tile URLs must also be allowed in CORS_OPTIONS and in the connect-src directive of the Talisman configuration, or the browser will block the tiles. Confirm these settings against the map tiles documentation for your Superset version before you promise a map to users.
Plan these items before rollout, not after the first dashboard fails: which base map and tile hosts are approved, who owns the Content Security Policy and CORS changes, and how many points the largest map is expected to draw. Large point sets are a data volume question as well as a rendering question, because every point a chart requests comes from your analytics database. Ask your team to size the expected row counts per query and test the heaviest map against a realistic dataset in staging, since those results will decide whether you need aggregation, filters or a different chart type.
Base map options and when each fits
This table compares the three ways to supply deck.gl base map tiles in Superset: the default OpenStreetMap, Mapbox with an API key, and a custom tile server set through DECKGL_BASE_MAP. Read each row as a decision criterion, and use the trade-offs column to decide which tile source your data and operating model can support.
| Decision factor | OpenStreetMap default | Mapbox tiles | Custom tile server |
|---|---|---|---|
| Setup required | None, since no API key is needed | Set MAPBOX_API_KEY and manage the key | Host tiles, then set DECKGL_BASE_MAP and related settings |
| Key management | No key to rotate or protect | Key stored in configuration, rotated and scoped by your team | Depends on your tile server's access controls, if any |
| Data egress to a third party | Map requests go to OpenStreetMap tile infrastructure, so confirm this meets your policy | Map requests go to Mapbox, so confirm this meets your policy | None, if tiles are served from your own network |
| Licensing and attribution | Confirm OpenStreetMap tile usage terms for your traffic level | Governed by your Mapbox agreement and pricing terms | Your organization licenses the tile data and hosts it |
| Tile hosting responsibility | Provided by the public tile service | Provided by Mapbox | Your team owns uptime, caching, updates and capacity |
| CSP and CORS changes | Confirm defaults cover the tile host in your build | Add tile URLs to CORS_OPTIONS and the Talisman connect-src | Add your tile URLs to CORS_OPTIONS and the Talisman connect-src |
| Effect on other base maps | Default is replaced only if you set a custom value | Replaced if DECKGL_BASE_MAP is set | DECKGL_BASE_MAP overwrites the defaults, so list every style you need |
| Best fit | Internal analysis where public tiles are acceptable | Teams already licensed for Mapbox and comfortable managing keys | Air-gapped, regulated or data-sensitive deployments |
How to configure deck.gl tiles in Superset
This sequence takes a self-hosted Superset from the default map setup to a deck.gl chart that loads base map tiles in a browser. Each step ends with a check so that a missing CORS or CSP entry is found before users report blank maps.
Choose the base map source
The platform owner decides whether deck.gl charts will use the OpenStreetMap default, a Mapbox style, or a custom tile server that your organization operates. Record the tile URL pattern, the domains it uses, and whether it needs an API key. OpenStreetMap is the default since Superset 6.0.0 and needs no key, while Mapbox needs MAPBOX_API_KEY. Done when the team has a written choice and the list of domains that the browser must reach.
Set the base map in configuration
Edit the Superset configuration file that your deployment loads, which is typically superset_config.py. For a Mapbox setup, set MAPBOX_API_KEY. For a custom tile server, set DECKGL_BASE_MAP, remembering that it replaces the default base map entirely. Confirm the exact syntax for your release in the map tiles documentation and UPDATING.md before editing. Done when the file parses without errors in a test run of the application.
Allow tile domains in CORS options
Add the tile server origin to CORS_OPTIONS so the browser can request tiles from the Superset origin. This is usually a change to the application configuration, so the platform team should review it alongside the rest of the origin list. Check that the origin matches the scheme, host, and port exactly, because a mismatch fails silently in the browser. Done when a request from the Superset origin to the tile server is no longer blocked by CORS in the browser developer tools.
Add tile URLs to the Talisman connect-src
Add the same tile domains to the connect-src directive of the Talisman content security policy configuration. Without this entry, the browser will refuse to load tiles even when CORS is correct. Keep the list limited to the domains you named in step one, and avoid wildcards unless your security team has approved them. Done when the browser console shows no content security policy violations for tile requests.
Restart the web tier
Restart the Superset web processes so the new configuration is loaded, and restart any other process that reads the same configuration file. In a container or Kubernetes deployment, this usually means rolling the web pods so that all replicas pick up the same settings. Check the startup logs for configuration errors and confirm that every replica reports the same values. Done when no replica is running the old configuration.
Verify tiles load in a deck.gl chart
Open a deck.gl chart, such as a scatter or polygon chart, in a browser that signed-in users use and wait for the map to render. Open the browser developer tools and confirm that tile requests return successfully and that no CORS or content security policy errors appear. Test with at least one account that has the dashboard permissions users will have. Done when tiles render at several zoom levels and the console is clean.
Record the configuration for upgrades
Store the base map choice, the API key reference, the CORS entries, and the connect-src entries with the rest of the deployment configuration in version control or your configuration management system. Because the tile settings span three places, a Superset upgrade or a change to the security policy can remove them without notice. Review UPDATING.md before each upgrade and repeat the verification step afterward. Done when another engineer can rebuild the setting from the record alone.
Why CSP and CORS settings block map tiles
A correct tile URL can still produce a blank map. The browser, not Superset's server, decides whether a tile request is allowed. Content Security Policy (CSP) tells the browser which origins a page may connect to, and cross-origin resource sharing (CORS) decides whether the browser may read the response that comes back from another origin. A map tile is fetched by the browser from the tile host, so if either rule rejects that host, the request fails silently from the chart's point of view and the base map stays empty while the data layers still render. When a map looks blank after a tile change, check the browser console for CSP or CORS errors before you suspect the tile server or the query.
Three places must agree for each tile origin. The first is the tile URL set in DECKGL_BASE_MAP, which is the only place that names the host. The second is CORS_OPTIONS, which must allow that origin. The third is the connect-src directive in the Talisman configuration, which must list the same origin so the browser permits the connection. Changing one without the others is the most common cause of partial failures. Record the origin, the reason it is needed, and the owner in a single change ticket, so the three entries can be reviewed and removed together when a tile provider is retired.
Security teams should treat each added origin as a new outbound trust decision. Ask for the list of tile hosts in use, confirm that each one is required by a chart the business uses, and remove any default or test origin left from setup. Avoid wildcard entries in connect-src and CORS_OPTIONS unless you can justify them in writing. Review the full set of response headers as part of your broader header and session work, which the Superset security hardening pages cover in more depth. Confirm the exact syntax for these settings against the map tiles documentation and the configuration reference for your Superset version before you change production.
How large point sets affect map performance
A deck.gl map draws every point the query returns, so the size of the result set is the first thing to control. The four drivers below act on different parts of the stack: the warehouse, the network, the browser and the cache, which means each needs its own mitigation.
Points returned by the query
Every row the chart query returns becomes a point the browser must draw and hold in memory. A dataset of raw event coordinates can return far more rows than a map can show usefully. Before rollout, check how many rows each map query returns at the widest filter setting users are likely to choose. Evaluate pre-aggregation into grid cells or H3-style bins in a virtual dataset, and set row limits on the chart so an unfiltered view cannot pull the whole table.
Warehouse cost per filter change
Each time a user changes a filter, Superset sends a new query to the database, so a map with several controls can generate a burst of heavy scans. Cost depends on how the coordinates are stored, whether the filter columns are indexed or partitioned, and how many charts share one dashboard. Check the query plan for the slowest filter combination with the warehouse team, and confirm which filters can be native dashboard filters with defaults rather than open-ended selections.
Browser rendering load
Even when the query is fast, the browser must transform and render the full point layer, and that work scales with the number of points on screen and the number of layers. Laptops and older workstations feel this first, especially in embedded dashboards that show several maps at once. Test with the largest realistic result set on the hardware your users actually have, and consider zooming or clustering behavior before adding more layers to the same chart.
Caching behavior
Superset's cache stores query results, so identical map requests can be served without hitting the warehouse again. Caching helps only when filter values repeat, and large point sets can exhaust cache storage quickly if each variation is cached as a full result. Decide the cache timeout per dataset based on how fresh map data must be, and confirm with your administrators how the caching layer is sized and where it runs. The cache configuration is set in the Superset configuration, so check it during performance testing rather than assuming defaults.
Security risks in map tiles and API keys
Map tiles look like static assets, but each one is a browser request to a third-party or internal host, and each widened security setting extends what the browser may contact. The cards below cover where keys sit, which hosts receive traffic, who can reach internal tiles and how changes to CSP and CORS get reviewed.
Mapbox API key exposure
When Mapbox is the base map, the access token is sent to the browser so deck.gl can request tiles. Anyone who opens the dashboard can read that token from browser traffic. Confirm with your Mapbox account which token scopes are available, whether URL restrictions can be applied, and who holds rights to rotate the token after a suspected leak. Setting MAPBOX_API_KEY in configuration does not keep the key from the client.
Origins the browser contacts
Every tile host in the base map setting becomes an origin the user's browser connects to directly, not through Superset's web server. Each origin can log the client IP address, user agent, referrer and the tile coordinates being viewed, which reveals the geographic area of interest. List every tile host in your design document, and confirm each one's data handling terms with its operator.
Access control for internal tile servers
A self-hosted tile server holding internal maps, such as facility plans or asset locations, must enforce access itself because Superset does not proxy tile requests. Decide whether tiles are public within your network, behind your identity provider, or unavailable outside a specific segment. Test that an account without dashboard access cannot fetch tiles by requesting them directly.
Widening CSP and CORS settings
Adding a tile host requires entries in CORS_OPTIONS and in the connect-src directive of the Talisman configuration. Each entry relaxes browser protection for that origin, so the change should not be made ad hoc in a running environment. Ask the team that owns headers to approve the exact origin strings, and keep them in version-controlled configuration.
Change control for tile configuration
Changing the base map, switching providers or moving a tile server alters what every viewer's browser contacts, so treat it as a production change. Record the old and new origins, the reason, the reviewer and the rollback step, then verify in staging that charts render for a non-admin test account. Pair this review with the broader hardening checklist for headers, secrets and access before the change goes live.
Questions buyers ask about Superset map setup
What does it cost to add deck.gl maps to Superset?
The cost comes from three places: your internal effort, any tile provider fees, and the partner scope if you hire help. Internal effort covers deciding on a base map, updating configuration, and testing charts in each browser your users run. Tile provider fees depend on the provider you choose. OpenStreetMap is the default deck.gl base map from Superset 6.0.0 and needs no API key, so it has no key cost of its own. Mapbox needs a MAPBOX_API_KEY, so its pricing and terms apply to your account. A custom tile server adds hosting and operations costs that recur. Most of the setup is one-time work, while tile hosting and provider charges recur. Ask any partner for a quote built from a written scope that lists each map type, each tile source, and each environment to be tested.
How long does Superset map setup take?
Duration depends on how many tile sources you use, how many map chart types you build, and how many environments and browsers must be checked. A single base map change through DECKGL_BASE_MAP is a small configuration task. Adding a custom tile server, updating CORS and Content Security Policy settings, and testing large point sets take more time because each step can affect the others. Ask for a timeline in the written scope that separates configuration, security review, and performance testing, and confirm which of those your own team will own.
What does the work need from our team?
Plan for four inputs. First, network access so browsers can reach the tile URLs and, if you host tiles yourself, so the tile server can be reached from user networks. Second, a decision on the tile provider, including whether data may leave your network and whether a key is allowed. Third, a security review of the Talisman connect-src value and CORS_OPTIONS, since tile URLs must be added to both. Fourth, browser testing across the browsers and devices your analysts use. Confirm these owners and access requests before the build starts, because they often decide the schedule.
Can our team set up deck.gl maps without outside help?
Yes, if your team already runs Superset and can edit its configuration file and deploy changes. The steps are a base map choice, environment settings, CORS and Talisman updates, and chart testing. The harder part is validating large point sets and confirming that policy settings did not block tiles in production browsers. Teams without a Superset administrator or without browser test capacity usually benefit from a written scope with a partner for those checks. Either way, test in staging first, as the upgrade guidance recommends for any configuration change.
Does a custom tile server change our Superset upgrade work?
Yes, it adds work at every upgrade. Custom tiles are set with DECKGL_BASE_MAP, which overwrites the defaults, so your value must be reviewed whenever the configuration changes. The tile URL also has to remain in CORS_OPTIONS and in the Talisman connect-src list. Before each upgrade, check the release notes in UPDATING.md for changes to map or security settings, then test maps in staging. You will also need to keep the tile server patched and backed up, which is separate from Superset itself.
Why do maps fail in the browser even when Superset loads?
The most common cause is a blocked request. The browser may refuse tile requests because the tile domain is missing from the Content Security Policy connect-src list, or because CORS does not allow it. Check the browser console for policy or CORS errors first. A second cause is an unreachable tile host from the user network, which is a firewall or proxy issue. A third is a DECKGL_BASE_MAP value that does not match the tile URL format your provider expects. Confirm each item in staging before you change production.
Is a large point set going to slow down our dashboards?
It can. Map rendering cost grows with the number of points the browser must draw, and the query that feeds the map adds load on your warehouse. Reduce the point count in the query, aggregate where users do not need individual points, and test the largest realistic dataset in the target browsers before rollout. Ask the partner or your own team to report render times and query times separately, because they usually have different fixes.
What to confirm in your environment before rollout
Map features depend on details that differ between Superset versions, networks and licensing arrangements. The cards below turn those dependencies into questions to settle with your vendor, the documentation and your own test environment before the build starts.
Superset version and base map default
Confirm which Superset release you run before you plan the base map. Superset 6.0.0 made OpenStreetMap the default deck.gl base map, so an older installation may still expect a Mapbox key or behave differently. Check the release notes for your version in UPDATING.md, then load a deck.gl chart in staging and record which tile source it requests. Do not assume the behavior carries over from a newer tutorial or from a different team's instance.
Outbound network access to tile origins
Ask your network and security teams whether browsers on your user networks can reach the exact tile origins you choose. Restricted or air-gapped networks may block public OpenStreetMap tile hosts or Mapbox endpoints, and the failure often appears only as blank map panes. List every origin in the tile URL template, including subdomains, and test from the same network segments your analysts use, not only from a server.
Mapbox licensing and key ownership
Confirm with your legal or procurement team who holds the Mapbox account, which plan covers your expected map views, and who rotates the key when staff leave. Mapbox needs the MAPBOX_API_KEY setting, so the key lives in your configuration and deployment secrets. Check the current Mapbox terms yourself, since usage terms and pricing are set by that provider and change over time.
Tile server capacity and hosting
If you host your own tiles, confirm who operates the tile server, how much traffic dashboards will generate at peak, and whether the server sits inside the same trust boundary as Superset. Each pan and zoom requests tiles, so a popular dashboard can multiply load quickly. Ask the tile server operator for their capacity numbers and caching behavior, and load test with realistic dashboard use before any user sees it.
CSP and CORS entries for each origin
Confirm that your security team will approve the origins you add to the Talisman connect-src setting and to CORS_OPTIONS. Each custom tile origin needs both entries, and a missing one blocks tiles without a clear error in the user interface. Record the exact origins in your change request so security reviewers see what was allowed and why, and so a later tile change does not silently widen the policy.
Browser support in your standard
Check your approved browser list and whether deck.gl charts render with WebGL in managed desktops and virtual sessions. Some hardened browsers, older builds and remote desktop setups disable or limit WebGL, which stops point layers from drawing. Test on the exact browser versions and hardware your analysts use, and confirm your policy allows the browser features Superset requires.
What Superset upgrades change for map tiles
The most important change for existing deployments is that Superset 6.0.0 made OpenStreetMap the default deck.gl base map. OpenStreetMap needs no API key, so a deployment that relied on Mapbox tiles without setting an explicit base map may now render different tiles after the upgrade. Teams that configured MAPBOX_API_KEY should confirm in their own environment whether their maps still use Mapbox after the upgrade, and whether the key is still needed. Map tiles are a rendering dependency, so a change here can look like a successful upgrade while silently altering what users see, which matters most for maps that carry licensing or branding requirements.
Before each upgrade, read UPDATING.md in the Superset repository for the versions between your current release and the target, and record every entry that touches map configuration, base maps, or the security settings that map tiles depend on. The upgrade guide also asks teams to back up the metadata database, run superset db upgrade and superset init, and test in staging first. Map testing should be part of that staging run, not a separate later task. Verify each base map a dashboard uses, the Mapbox key behavior, and any custom DECKGL_BASE_MAP value against the new release, and confirm that tile requests still succeed under the CORS and Content Security Policy settings in place.
Ask your upgrade plan to name an owner for map behavior and a rollback step if tiles fail after production cutover. Note that the 7.0.0 release candidate is listed as a pre-release on the releases page, so teams planning ahead should confirm the map tile documentation for whichever version they target rather than assuming the 6.0.0 behavior carries forward unchanged. Treat the release notes and the map tiles documentation as the reference for each target version.
How DeployOpen scopes and delivers map setup
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For deck.gl maps in Superset, we start by agreeing which base map provider, tile source and network paths your organization can use, then build and hand over the configuration in your environment.
How we scope
- Engagements are fixed-scope, with the map tile source, data sources and deliverables agreed in writing before work starts.
- The written scope names the base map choice, whether OpenStreetMap or Mapbox tiles, and any custom tile server your network allows.
- We confirm the approximate point volume and map use cases, since these shape the performance testing the scope includes.
How we build
- We set DECKGL_BASE_MAP and the related keys in your Superset configuration, using secrets stored outside the image where your policy requires.
- We align CORS_OPTIONS and the Talisman connect-src entries with the exact tile URLs, so browsers load tiles without widening access.
- We test map charts against representative datasets in staging, measuring render behavior and query load before any wider release.
How we hand over
- You receive the configuration changes, a record of the tile providers and domains allowed, and the reasons behind each setting.
- Documentation covers how to add or change a tile source, including the CSP and CORS updates that every change requires.
- We walk your operators through the test results and the limits we observed for large point sets, so the team can plan around them.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, covering map changes across future Superset releases.
- When you upgrade Superset, we review the UPDATING.md notes for map-related changes and retest tile loading before rollout.
- Support requests on tile errors, CSP violations or slow map rendering are handled against the documented configuration for your environment.
