Why Apache Superset deck.gl maps need your own tile source
Custom map tiles let deck.gl charts in Apache Superset draw their base map from a server you choose, instead of a default external provider. Teams need this when their geospatial dashboards must run inside a restricted network, when their data policy forbids sending viewer locations or dashboard context to third-party map services, or when they hold a commercial tile agreement that dictates which endpoints the charts may call. The base map is the layer users see first, so the choice of where it loads from is a configuration decision with security effects, not a cosmetic one.
Superset's deck.gl map charts read their base map from the DECKGL_BASE_MAP setting in superset_config.py, and that setting determines which hosts the browser contacts when someone opens a dashboard. Each external tile endpoint also brings its own authentication, key handling and content security policy requirements. Before you change anything, list every map source your current charts use, record which browser requests they generate, and confirm with the tile provider which URL patterns, access keys and terms apply to your deployment. Also confirm whether your Superset version exposes the same options in the configuration reference you are targeting, since settings can change between releases.
Once the source is chosen, treat it as part of your security review. A tile server that sits inside your network changes who can see viewer traffic and where logs live, and an external commercial provider changes your data sharing obligations and key management. Plan who owns the tile key, how it is rotated, and how a change to the base map is tested in staging before it reaches production dashboards. The sections below cover the settings, the CORS and Talisman changes, and the steps for serving tiles inside restricted networks.
Which tile source fits each deployment
This table compares three ways to supply map tiles to deck.gl charts and what each one asks of your configuration, keys, browser policies and operations. Read each row against the network your users work from. The main takeaway is that browser-facing options need Talisman and CORS entries that match the tile host, while a restricted-network server moves the upkeep to your own team.
| Tile source | DECKGL_BASE_MAP entry | Keys, CORS and Talisman | Who maintains it |
|---|---|---|---|
| Commercial provider with API key | Style URL entry, with the key supplied through MAPBOX_API_KEY where the provider uses it | Key reaches browsers, so restrict it by domain in the provider console. Allow the provider host in Talisman and CORS settings. | Provider runs the tiles. You own the key, usage limits and compliance with provider terms. |
| Self-hosted tile server reachable from browsers | Style or tile URL on your own host, listed in the same format as other entries | No provider key is needed. Allow the tile host in the Talisman content security policy and set CORS for its origin. | Your team runs the server, certificates, map data updates and capacity. |
| Tile server inside a restricted network | Internal URL on a private host, reachable only from the user network | Internal host must still be allowed in Talisman and CORS. Fonts and other assets must also load from inside the network. | Your team, with fixed processes for updating map data and patching the server. |
| Where user map requests go | Depends on the host you list in the entry | Browsers request tiles directly from the listed host, so that host's logs and IP exposure apply to your users. | The provider, your team or your network team, depending on where the host sits. |
| What to confirm before choosing | Exact entry format for your Superset version | Provider terms, key rotation and allowed domains, plus Talisman and CORS behavior in your release. | Provider terms, your security team and the Superset documentation for your version. |
How to configure DECKGL_BASE_MAP step by step
This sequence takes a deck.gl chart from the default base map to a tile source you choose, with each change checked in the browser before the next one starts. The result is a test dashboard that renders map tiles from a host your organization controls or has approved.
Choose and document the tile source
Decide whether tiles come from a server you run inside your network, a commercial provider, or a self-hosted tile set served from your own storage. Record the exact tile URL template, the host name, whether the provider requires an API key, and the licensing terms that govern display and caching. Your security team should approve the host before any configuration changes are made. Done means you have a written entry with the host name and the key owner, and you can open one sample tile URL in a browser and see an image returned.
Set DECKGL_BASE_MAP in superset_config.py
Edit the superset_config.py file that your deployment loads, and set DECKGL_BASE_MAP to the list of map style entries your organization needs. Each entry names the map style and points to the tile source you recorded in the previous step. Keep the file under version control so the change can be reviewed and rolled back. Check the syntax by starting the Superset application once in a non-production environment and confirming that it loads the configuration without an import error in the logs.
Supply any map key through configuration
If the tile provider requires a key, place it in an environment variable or your secrets manager and reference it from the configuration file, not as a literal string in code or in a committed file. Confirm with the provider which key type is needed for browser use and whether it can be restricted to your Superset hostnames. Verify the change by checking that the rendered configuration in the running container shows the key reference and that the key value does not appear in the repository, image layers or application logs.
Adjust CORS and Talisman for the tile host
Add the tile host to the content security policy so the browser is allowed to request tiles, and review the CORS settings if your tile server requires cross-origin access. Changes to Talisman settings should be limited to the directives that load map resources, such as image and connect sources, and reviewed by your security team. Confirm the result by reloading a dashboard with the browser developer tools open and checking that no content security policy violation is reported for the tile host.
Restart and rebuild the application as needed
Restart the Superset web service so the new configuration is loaded. If your deployment bakes frontend assets into the image, rebuild the image and redeploy it, because configuration changes that touch frontend behavior may not take effect until the assets are rebuilt. Confirm the restart by checking that the web process started cleanly and that the application version and configuration reference match what you deployed.
Verify tile requests in the browser
Open a dashboard that contains no deck.gl chart and check the browser network panel for requests to the tile host, confirming they return a successful status and image content. Then check the console for errors. Failures at this stage usually point to a wrong URL, a missing key, a blocked origin or a content security policy rule, so fix the earlier step that matches the error before continuing.
Confirm a deck.gl chart renders in a test dashboard
Create or open a test dashboard in a non-production instance, add a deck.gl chart with a map style from your configured list, and load it with a user account from the role that will use it. The chart is complete when the base map tiles appear under the data layer, the network requests to the tile host succeed, and the browser console shows no errors related to maps or content security. Record the screenshot, the configuration version and the test user so the check can be repeated after upgrades.
Security risks when Superset loads map tiles from outside
Every deck.gl map tile request leaves the browser and carries something of yours with it. The cards below cover the credentials, policy changes, data exposure and maintenance duties that come with a tile source, so you can decide which are acceptable before a map reaches a dashboard.
API keys exposed in the browser
Tile provider keys placed in DECKGL_BASE_MAP are delivered to every browser that loads a dashboard with a map chart. Anyone who can view the chart can copy the key from the network requests and use it elsewhere, possibly running up usage charges on your account. Before rollout, confirm whether the provider supports domain or referrer restrictions, usage caps and key rotation, and whether a key that can be restricted to your Superset hostname is available for the tiles you need.
Widened content security policy
Loading tiles from a new host requires allowing that host in the browser's content security policy, typically for connect and image sources. Each added origin lets the page fetch resources from one more party, so the change should be reviewed by the team that owns Superset's headers and documented as an exception. Check the Talisman settings in your configuration and confirm the exact directives your tile source needs, rather than copying a broad wildcard.
Viewer location and dashboard context leaking
A tile request reveals the viewer's IP address, browser and the visible map area, and the request URL can expose the tile coordinates being viewed. For a map over customer addresses, facilities or field operations, that pattern can disclose more than the chart itself. Ask the provider what it logs, how long it retains request data, and whether it processes data outside the regions your policies allow, and record the answer in your data inventory.
Unpatched tile servers
A self-hosted tile server, such as one serving vector or raster tiles in a restricted network, becomes part of your attack surface and needs the same patch cycle as Superset itself. An unpatched tile server or its map style files can serve tampered content into dashboards, and a neglected server is easy to forget during upgrades. Assign an owner, add it to vulnerability scanning and confirm how updates to tile data and styles are tested before they reach users.
Map credentials handled like SECRET_KEY
Tile keys and tokens written into superset_config.py or environment files sit beside the SECRET_KEY, which Superset requires to start. Those values should follow the same rules: restricted file permissions, secrets injected from a vault or orchestrator rather than committed to source control, a documented rotation procedure and access limited to the people who run the deployment. Confirm how your team stores and rotates these values before adding them to configuration.
Serving map tiles inside restricted networks
Plan the tile host as an internal dependency from the start: browsers on the internal network should never call a public tile or style host, so every tile and style asset that a deck.gl chart requests must resolve to a host you run or control. Start by deciding where the tile data comes from. Options include an internally hosted tile server built from data you license and are permitted to store, a copy of a commercial provider's tiles that your license terms allow you to self-host, or a vector tile set generated from open geographic data. Confirm the license terms for each source in writing before anything is copied into the restricted zone, because a commercial key that works online may not cover offline hosting.
Treat tile and style refreshes as controlled changes. Each new tile set, style file or font glyph bundle should move through the same change process as application code: it is staged in a lower environment, rendered against a set of reference dashboards, approved, and then imported into production with a record of its source version and checksum. Tie the style file to the tile set version it expects, so a refresh cannot silently break labels or layers. Keep the previous version available so you can roll back a tile set that renders incorrectly.
Route the tile host through the same proxy path that serves Superset, or through an equivalent internal path that your reverse proxy and Content Security Policy already allow, so the browser sees only internal origins. Check that the DECKGL_BASE_MAP entries, the Content Security Policy directives and any CORS settings all point at the internal host. The render path that matters most is the one that runs without a user's browser: alerts and reports, and dashboard thumbnails, are rendered by a headless browser in the worker. That process needs network access to the internal tile host, and its trust store must accept any internal certificate. Test that path directly, because blank map panels in reports often come from a worker that cannot reach the host even when interactive users see the map. Verify the results in your own environment, since behavior depends on your proxy, network segmentation and browser versions.
Limits to confirm before you change the base map
Changing the base map touches the rendering library, a third-party provider and every consumer of the dashboard, from scheduled reports to thumbnails. Each card below is a limit to confirm in your own environment before the change goes to production, and the checks overlap, so verify them together.
Superset version and DECKGL_BASE_MAP behavior
Confirm which Superset release you run and whether the DECKGL_BASE_MAP option behaves as its documentation describes in that exact release. Configuration keys and deck.gl handling can change between versions, so a setting that worked after one upgrade may not work after the next. Read the release notes for your target version, including the 6.1.0 and 7.0.0rc2 entries, and test the change in staging before you rely on it.
Provider terms and key scope
Commercial tile providers set their own terms for usage volume, display, caching and redistribution, and API keys are often limited to specific domains or services. Confirm that your planned use, including use inside a private network, is allowed under the contract you hold. Restrict keys to the Superset origin where the provider supports it, and record who owns the key and where it is stored.
Tile licensing for offline copies
Serving tiles from your own server or caching them for a restricted network is a different license question from viewing them through a public endpoint. Many tile sources restrict downloading, bulk export or offline storage, and some data licenses require attribution in the rendered map. Ask the data owner or provider in writing whether self-hosted or cached tiles are permitted for your use case.
Browser support for the rendering library
The deck.gl layer relies on WebGL in the viewer's browser, so a base map that renders on current desktop browsers may fail on older browsers, locked-down kiosks or virtual desktops without GPU acceleration. Confirm the browsers and devices your analysts use, and test map rendering on each. Also check the browser policies that control WebGL and any content security settings that block tile hosts.
Scheduled reports and thumbnails
Scheduled reports and dashboard thumbnails are rendered by the Superset worker rather than by an analyst's browser, so they depend on the worker's network path to the tile server. Confirm whether these reports use the same base map as the interactive dashboard, and check that the worker can reach the tile host through your proxy or firewall. A map that loads on screen but is blank in an emailed report is a common failure to test for.
Questions teams ask before changing Superset map tiles
How much effort does changing the map tile source in Superset take?
Pointing an existing deck.gl chart at a different tile source is usually a small configuration change, but the effort grows with everything that depends on the tile URL. The main drivers are how many dashboards and charts use deck.gl maps, whether the new source needs an API key or a token, whether it sits behind a proxy or inside a restricted network, and how many people must approve the change. Effort is highest when the tile host is not yet chosen, because licensing, hosting and security review come before any configuration. Ask the partner to break the work into configuration, network validation, test dashboards and rollout, and to state which parts are one-time and which recur, such as renewing keys or updating tile styles.
Can our own team change Superset map tiles without a partner?
Yes, a team that already runs Superset can usually make this change in-house, provided it has someone who can edit the deployment configuration, rebuild or redeploy the application, and test deck.gl charts in a non-production instance. The configuration itself is documented in the Superset configuration reference, so the harder parts are usually operational: confirming that browsers can reach the tile host, handling keys without exposing them, and checking that exports and thumbnails still render. A partner adds most value when the tile server must run inside a restricted network, when several environments must stay consistent, or when the team lacks capacity to test across roles and dashboards.
What do we need to provide before a tile source change starts?
You need to provide four things: the identity of the tile host (the domain or internal hostname, the provider, and who owns the account), the network path from user browsers and from the Superset web and worker services to that host, a list of dashboards and charts that use deck.gl maps, and a non-production Superset instance with a test dashboard that exercises each map type. Also name the person who can approve use of the provider's terms and any API key, and the person who will rotate that key later. If the tile host is internal, confirm which network segments can reach it and whether certificates are issued by an internal authority that browsers trust.
Does changing the tile source affect reports and thumbnails?
It can. Superset's architecture documentation says that alerts and reports, async queries and dashboard thumbnails require the caching layer and the worker components, and most installations use Redis and Celery for them. Scheduled reports and thumbnails are rendered server-side by workers, so those workers must reach the new tile host too, not only user browsers. A tile source that works in a browser session can still produce blank or grey map areas in a report if the worker cannot reach it, the key is missing from the worker environment, or the render timing differs. Test a report and a thumbnail for each deck.gl chart type after the change.
Which settings must be checked for CORS and Talisman when using a new tile host?
Check three areas: the tile host's CORS response headers, the Content Security Policy that Talisman applies to the Superset web application, and any proxy in front of Superset. Browsers will request tiles from the new origin, so the host must allow the Superset origin and must return the headers the map library expects. Talisman, when enabled, sets a Content Security Policy that may block tile, image or script origins that are not listed, so the connect and image sources must include the new host. Confirm these settings in the Superset configuration documentation for your version, and test with the browser developer tools open, since blocked requests often fail silently on the map.
Can we serve map tiles entirely inside a restricted network?
Usually yes, but it is a separate project. The tile server, its data and its styles must be hosted inside your network, and every client that renders maps, including browsers and worker services, must reach it without internet access. Plan for updates to tile data, storage capacity, the certificate chain used internally, and how fonts and sprites used by map styles are served. Confirm with the tile server vendor or project which licenses cover self-hosting and which data sources you may redistribute internally. This work overlaps with font and asset hosting for restricted networks, so coordinate the two.
What should a quote for a Superset map tile change include?
A quote should follow from a written scope and list each deliverable separately. Ask it to name the tile hosts in scope, the Superset environments it covers, the configuration changes to DECKGL_BASE_MAP entries and any key handling, the CORS and Talisman review, the network validation from browsers and workers, the test dashboard and its test cases for each deck.gl chart type, the report and thumbnail checks, and the handover notes. Ask which costs are one-time and which recur, such as tile hosting, provider fees and key rotation, and who pays each. Ask for the assumptions the quote depends on, including the number of environments and whether a restricted network is involved.
Keeping custom map tiles working through Superset upgrades
Map tile configuration is easy to lose during an upgrade because it lives in settings that no one reviews once the charts look right. Treat the DECKGL_BASE_MAP entries, any Mapbox key reference, the CORS and Talisman settings that let the browser load tiles, and the tile server hostnames as part of the deployment, and retest them every time the Superset version changes. The Superset upgrade documentation sets the baseline: back up the metadata database, run superset db upgrade and superset init, and test in staging first. Those steps confirm the application starts and migrates, but they do not prove that a deck.gl chart still draws its basemap.
Before you move to a new version, read the breaking change notes in UPDATING.md for the releases between your current and target versions. Look for changes to chart plugins, deck.gl or map-related controls, and security headers, since a tightened content security policy or a changed Talisman default can block tile requests from a browser without any error on the server. Ask your Superset team or partner to list every map-related setting in your configuration and to confirm which of them the release notes touch. Record the result in the change ticket so the reviewer can see what was checked.
Keep the tile configuration in version control alongside your Superset configuration file and image build, with the tile server URLs, style references and header allowances reviewed like other code. Store any Mapbox key outside the repository, in your secrets manager, and confirm with your own security team how it is injected into the container at runtime. After each upgrade, load a map-based dashboard in staging from a clean browser session, check the network log for blocked tile requests, and compare the rendered basemap with the previous version before promoting the change to production.
Decisions to settle before the build starts
Map tiles touch licensing, security, network design and release management at the same time, so the choices below interact. Settle them in writing before the first chart renders, because each one changes the configuration, the approval path and the test plan that follow.
Which tile source is authoritative
Decide whether tiles come from a commercial provider, a tile server you run, or a static tile archive you host. Each option has different licensing terms, usage limits and failure modes. Record one authoritative source per environment so that development, staging and production do not quietly point at different providers. Ask the provider to confirm in writing which attribution text must appear on charts.
Who owns keys and rotation
Any commercial tile provider key placed in DECKGL_BASE_MAP is visible to every browser that loads a dashboard, so treat it as a public credential and restrict it by domain where the provider allows. Name an owner for the key, a rotation procedure and the place where the new value is stored. Confirm how a rotated key reaches running Superset instances without a manual edit on each one.
Whether maps must work offline
Decide if dashboards must render maps on networks with no route to the internet. If they must, tiles and any style or font files need to be hosted inside the restricted network, and the build has to cover that hosting from the start. If they need not, document the outage behavior so users know a blank basemap means a network or provider problem, not a broken chart.
How CSP exceptions are approved
Tile hosts must be allowed in the content security policy, and the Talisman settings that enforce it are a security control, not a styling detail. Agree who reviews each added host, which hosts are permitted, and how a new tile domain gets approved. Keep a record of each exception with its reason and owner so an auditor or a later upgrade can trace why it exists.
How tile data is refreshed
If you serve your own tiles, decide how often source data is rebuilt, who triggers a rebuild, and how a bad build is rolled back. Tiles cached by browsers or CDNs can show stale boundaries for some time after a change, so confirm the cache lifetime you accept. Test that a refreshed tileset loads in an existing dashboard without changing the chart configuration.
Who tests render paths after upgrades
deck.gl and map configuration can behave differently after a Superset upgrade, so the upgrade plan needs a named tester for map charts. Check the UPDATING.md notes for each target version and rerun the map dashboards in staging before production. Assign that owner before the first upgrade, not during an incident.
How DeployOpen works on this
DeployOpen plans and implements map tile configuration for self-hosted Apache Superset inside the infrastructure you control. We scope the tile sources, network paths and security settings in writing first, then build, test and document the change so your team can run it after handover.
How we scope
- Inventory every deck.gl chart and the tile source each one needs, whether self-hosted, commercial or internal.
- Record which tile server endpoints, CORS origins and Talisman content security settings the change touches.
- Agree the written scope, deliverables and timeline with you before any configuration work begins.
How we build
- Configure DECKGL_BASE_MAP entries and any provider keys through your secrets handling, not in shared code.
- Set CORS and Talisman policies narrowly for each tile origin and confirm charts load in every target browser.
- Stage tile serving inside restricted networks and test rendering against your Superset version before release.
How we hand over
- Deliver configuration files, a tile source register and a test checklist your team can rerun after changes.
- Document key rotation, tile server updates and the steps for adding or removing a base map.
- Walk your administrators through the configuration and the verification steps in a handover session.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Retainer work can cover re-testing map charts when Superset or your tile provider changes.
- Ask for the support scope and response expectations in writing alongside the initial quote.
