Apache Superset air-gapped deployment guide

Running Apache Superset in an air-gapped network

Picture a team that must give analysts dashboards on databases sitting inside an isolated network, with no route to the internet. Apache Superset can run there. The work is a set of planning and engineering decisions: container images built in advance with every database driver the team needs, map tiles, fonts and other assets served from inside the network, telemetry switched off, no sign-in path that depends on an external identity service, and a documented offline upgrade procedure. Superset is licensed under the Apache License 2.0 and has no paid edition, so none of this depends on buying a feature tier. The cost is engineering time and ongoing maintenance, which makes the scope and the people doing it the real questions.

Each architecture component needs an offline source before the first install. The Flask and React application, the metadata database, the optional caching layer and the optional Celery worker and beat processes each pull dependencies, images or packages that must be mirrored or baked into an internal registry and package index. Alerts, reports, async queries and dashboard thumbnails depend on the caching and worker components, so a team that plans only for the web tier will find those features failing at the boundary. Confirm with your security team which artifacts may cross into the enclave, how each one is verified, and who owns the mirror. The Superset architecture documentation is the reference for the component list.

The upgrade path is where air-gapped installs most often drift. Each new release arrives as a package you must fetch on a connected host, scan, transfer and install, and the database steps in the upgrade guide still apply: back up the metadata database, run the migration and initialization commands, and test in staging first. Read the breaking change notes in UPDATING.md for every version you skip. Also decide now how you will handle the Kubernetes packaging: the official Helm chart is marked deprecated in current development documentation, and the Kubernetes Operator is alpha with a v1alpha1 API that may change between releases, so confirm the supported install method for your target version before you build around it.

Which external dependencies to remove or replace

A Superset build that works on a connected laptop can still fail silently once it crosses an isolated boundary. The six areas below are where outside network calls usually hide, and each one needs an inventory against your own build, not a copied list.

Database drivers in the image

Superset does not ship drivers for every warehouse or query engine, so each database your analysts connect to needs its Python driver baked into an internal image. Build the image from a reviewed package set and confirm that every driver, its native libraries and its dependencies are present before the cluster goes offline. A missing driver usually appears only when a user first opens that connection, so test each one against a staging database inside the isolated network.

Playwright browser for reports

Alerts, reports and dashboard thumbnails depend on a headless browser that the worker drives. Its browser binaries are normally downloaded at install time, so the installer must pull them from an internal artifact store or you must bundle them into the image. Confirm the browser version matches what your Superset release expects, and test a scheduled report end to end, because a worker can start cleanly and still fail on first render.

Map tiles and map providers

Map charts load tiles from external servers by default, and users in an isolated network will see blank maps without any error on the dashboard. Decide whether you will host a tile server inside the network or use a locally licensed tile set, then point the map configuration at that source. Check every map-based chart type your team plans to use, since each may reference its own endpoint.

Fonts and static assets

Charts and the interface request web fonts and some icon sets from public content delivery networks. Find every external reference in the front-end build and in any theme you apply, then serve the font files from your own web tier. Test exported PDFs and images as well, since font substitution there can change how labels wrap and can break a report that looked correct on screen.

Outbound telemetry and update checks

Confirm which telemetry or version-check behavior your chosen Superset release has, and turn off every setting that sends data outward. Then verify the result by watching egress from the application host and worker for a full working day with real traffic, not just by reading the configuration. Record the settings you changed so the next upgrade review can compare them.

OAuth providers and Python packages

Login through a public OAuth provider or an external identity service needs a reachable endpoint, so replace it with a directory or identity provider inside the network, or keep local accounts for the initial rollout. Separately, every Python package for Superset and its drivers must come from an internal index or a mirror that you have verified, with hashes recorded for the upgrade process. Ask your team to document which package sources they trust and who signs off on new additions.

Choosing a deployment path for an isolated network

A virtual machine install suits teams that already run Linux servers and want the fewest moving parts. In an isolated network, the work is mostly about staging Python packages, OS packages and the libraries Superset needs before the host loses internet access. The team then owns the web server, the scheduler for alerts and reports, and the metadata database as separate services on that host or nearby hosts.

Package staging: Mirror the Python wheels, OS packages and any database drivers into an internal index before the install, and record their hashes.
Service sprawl: Superset's architecture lists an optional caching layer and Celery worker and beat processes. Alerts, reports, async queries and thumbnails need them, so plan how Redis and Celery are installed offline.
Metadata database: Use PostgreSQL or MySQL in production, not the SQLite default used by PyPI installs.
Manual patching: Your team carries every OS and Python security update through the transfer process.
Upgrade steps: Upgrades follow the project's documented sequence of database backup, upgrade and init commands, tested in staging first.

Confirm which PostgreSQL and MySQL versions your environment can mirror, since the configuration documentation lists supported ranges.

Container platforms move most of the dependency problem into a single image. You build or extend an image with the database drivers and any fonts or map assets it needs, push it to a registry inside the network, and run the same artifact in every environment. The registry, not the internet, becomes the source of truth for what runs.

Image contents: Bake drivers, fonts and offline assets into the image at build time so the running container needs no outbound calls.
Registry mirroring: Copy the base image, its digest and every tag you use into the internal registry, and pin by digest.
Scanning: Scan the built image inside the enclosure and keep the scan results with the release record.
Compose limits: The project does not recommend the bundled PostgreSQL container for production, so use an external metadata database.
Config delivery: Mount superset_config.py and inject SECRET_KEY at runtime rather than rebuilding the image per environment.

Confirm how your registry handles image signing and retention, because those settings decide how long an old image can be redeployed.

Configuration options and when each fits

This table compares the main offline choices for an air-gapped Superset: image build location, Python package delivery, map tiles, telemetry, and identity. Read each row for the update effort it adds and the attack surface it leaves, then match the option to your change cadence and isolation rules. The main takeaway is that every option that avoids the internet also moves patching and verification work onto your own team.

Decision	Option	Update effort and attack surface	When it fits
Image source	Fully prebuilt internal image with all drivers	Lowest build work on site, but every driver, library and Chromium version is frozen into one artifact that must be rebuilt and rescanned for each fix	Stable environments with a small set of approved database drivers and a clear release owner
Image source	Build on site from an internal base image	More moving parts inside the boundary and a larger build toolchain to secure, but drivers and patches can be added without waiting for a new artifact	Teams that need to add connectors often and already run an internal build pipeline
Python packages	Mirrored PyPI packages on an internal index	Dependency resolution still works on site and updates are routine, but the mirror must be kept in sync and its contents reviewed before they enter the network	Environments that rebuild images regularly and need dependency resolution without manual file handling
Python packages	Vendored wheels checked into a controlled repository	Smallest, most reviewable set of files and no index to run, but transitive dependencies must be collected by hand and each upgrade is a manual exercise	Small, slowly changing installs where each package can be reviewed and hash-checked before transfer
Map features	Internal map tile server	Adds a service to run, patch and monitor, and its tile data must be refreshed by transfer, but dashboards keep their map charts	Dashboards where geographic views are a business requirement
Map features	Disable map features	No extra service and no tile data to move, but map charts are unavailable, so users need an agreed alternative	Deployments where maps add little value and the reduced surface is preferred
Telemetry	Opt out of telemetry in configuration	No outbound calls to confirm and less to review, but you should verify the setting in your own environment because defaults can change between versions	Every air-gapped install; confirm the exact setting for your release in the configuration documentation
Identity	Local database accounts	No external dependency and nothing extra to patch, but account lifecycle, password policy and offboarding are manual and fully owned by the platform team	Small user populations or a short-term pilot
Identity	LDAP directory inside the network	Uses your existing directory and group membership for role mapping through AUTH_ROLES_MAPPING, but adds a bind account and directory exposure to Superset	Organizations whose access decisions already live in an internal directory
Identity	Internal OAuth2 server using the code flow	Central sign-in and token lifetimes, but the identity provider becomes a critical dependency that must be highly available inside the boundary	Organizations already running an internal identity provider with multi-factor authentication

Setup sequence for an offline Superset install

This sequence takes a Superset deployment from an inventory of dependencies to a verified offline instance that starts, renders reports and runs a test query without internet access. Each step closes with a check you can record as evidence before moving on.

Inventory every dependency before the build
The platform team lists what the offline instance must contain: the Superset release, the metadata database (PostgreSQL 10 to 17 or MySQL 5.7 and 8.x, per the Superset configuration documentation), a caching layer and Celery workers if you need alerts, reports, async queries or thumbnails, and every database driver for your warehouses. Add the Playwright Chromium build for reports, the fonts and map tiles your dashboards use, and the identity provider endpoints or LDAP directory that login depends on. Record the exact version of each item in a bill of materials. Done means the list is reviewed by the security owner and every item has a version, a source and an owner, with no unnamed gaps.
Build and scan the image in staging
In a connected staging zone, the build team creates a Superset image that already contains all drivers, the reporting browser, fonts and any internal assets, pinned to the versions in the bill of materials. The team scans the image for known vulnerabilities and checks that the Apache-2.0 license notices and package sources are recorded. Confirm the release you are pinning against the project's UPDATING.md notes and the GitHub releases page before you freeze it. Done means the image has a digest, the scan report is archived, and no package in the image pulls from a public index at runtime.
Transfer the artifacts with integrity checks
Export the image archive, the dependency bundle and the checksum manifest, then carry them across the boundary under your media-transfer procedure. On the isolated side, recompute each checksum and compare the image digest with the value recorded in staging. This is the control that supports the software integrity and authenticity verification expected of vendor software under NERC CIP-013-2 where it applies to your environment. Done means every hash matches, the transfer record names the people who approved the move, and a mismatch stops the process.
Provision the metadata database and SECRET_KEY
Platform engineering creates the metadata database inside the isolated network on a supported PostgreSQL or MySQL version, with its own backup schedule and a least-privilege account for Superset. Generate a unique SECRET_KEY and store it in your internal secrets manager rather than in the configuration file. Avoid SQLite, which the architecture documentation does not recommend for production. Done means the database accepts the Superset account, the key is injected as an environment value, and a backup of the empty database restores successfully.
Configure internal identity and assets
Point the configuration at internal services only: your LDAP directory or internal OAuth2/OIDC provider, with AUTH_ROLES_MAPPING set to your group-to-role decisions, and internal hosts for map tiles, fonts and any external resources the dashboards call. Disable telemetry and remove references to public endpoints from the configuration and templates. Confirm each external name with your own environment owners, since the list of outbound calls depends on the features you enable. Done means a network test from the Superset host shows no successful connection to public addresses, and a test login succeeds through the internal provider.
Initialize the database and start the services
Run the database migration and initialization commands from the upgrade guide inside the offline image, then start the web server, the caching layer and the worker and beat processes if your feature set requires them. Check the logs for attempted outbound connections, failed asset loads or missing driver errors. Done means the application starts without errors, the health endpoint responds through your internal proxy, and the logs contain no outbound connection attempts.
Verify reports, thumbnails and a test query
Run one scheduled report and one thumbnail generation to confirm that the reporting browser, fonts and worker queue work without internet access. Then execute a test query against an approved warehouse using a read-only account and confirm the result matches a value your data owner has already checked. Record the outcome of each check. Done means the report arrives at its internal recipient, the thumbnail renders with internal fonts, the query returns the expected result, and the evidence is stored with the change record.

Security and operational considerations offline

Once Superset runs without internet access, every security control that normally depends on a live feed has to be carried by your own process. The cards below cover the secrets, packages, patches, backups and access paths that you must own when nothing updates on its own.

SECRET_KEY ownership and rotation

Superset will not start without a user-specified SECRET_KEY, so the key must be generated, stored and injected from your own secrets store before first boot. Keep it out of superset_config.py and out of the transfer bundle. When rotating, set PREVIOUS_SECRET_KEY to the old value so existing sessions and encrypted data can still be read during the change. Confirm the rotation steps for your Superset version in the configuration documentation before you schedule a rotation window.

Integrity of carried packages

Every image, wheel, driver and archive that crosses the boundary should be checked against hashes or signatures recorded on the outside before it is imported. Regulated sectors apply the same logic: NERC CIP-013-2 expects procurement processes to address verification of software integrity and authenticity for vendor software and patches. Record who verified each item, when, and against which source, so the import can be audited later.

Patch cadence without live feeds

Without a live feed, you will not learn about a new Superset release or advisory on its own. Set a fixed review interval, track the project's releases page from an outside system, and decide in advance which releases you will carry in. Ask your DeployOpen team or internal owner to document how an emergency patch moves through the same review and transfer path as a routine one.

Metadata database backups before upgrades

The upgrade guide asks you to back up the metadata database before running superset db upgrade and superset init. Offline, that backup is the only way back if a migration fails, so store it on media you control and test a restore in staging. Confirm the backup format and restore procedure for your metadata database version, since dashboards, users and saved queries all live there.

Role mapping through AUTH_ROLES_MAPPING

If login uses LDAP or an OAuth2 provider inside the network, AUTH_ROLES_MAPPING translates directory groups into Superset roles. Review the mapping as part of every change, because a stale group name can grant more access than intended. Keep the mapping in version-controlled configuration, and confirm with your identity team how group membership is refreshed when no external feed is reachable.

Controlled access to the transfer path

The transfer media and the staging host that receive it are part of your security boundary. Limit who can mount the media, log each transfer session, and keep the transfer host separate from the production Superset network. Document who may approve an import and how a rejected package is quarantined. Confirm these controls with your security team and your sector's requirements before the first transfer.

How to upgrade Superset when nothing can be downloaded

Treat every Superset upgrade in an air-gapped network as a single tested bundle that you build outside the boundary, verify, rehearse in staging, and only then carry across. The documented sequence starts with a backup of the metadata database, because superset db upgrade and superset init change that schema and the only clean way back is a restore. Before the bundle crosses, read UPDATING.md in the release you are moving to and list every breaking change against your own superset_config.py, custom images and installed drivers. The Upgrading Superset documentation is the reference for this order of operations, and your change record should show that you followed it.

Plan the cadence around the release dates that PyPI shows. Apache Superset 6.0.0 was published on December 18, 2025 and 6.1.0 on May 13, 2026, so a gap of roughly five months between two minor releases is the pattern to budget for, though your own cycle will depend on your change windows and approval times. The GitHub releases page lists 7.0.0rc2 as a pre-release dated October 16, 2026. A release candidate is not for production, so do not build it into an offline bundle or a staging baseline. Confirm with the project which release is current when you plan, because the list changes.

Build the bundle so that the image or wheel set, the drivers for each database, the Chromium build used for reports if you run them, fonts and map assets, and the migration commands all come from the same tested version. Check the package hashes or image digests against the values you recorded at the source, because the transfer is where a substituted file would enter. Run the full upgrade in a staging copy of the production metadata database, then confirm dashboards, datasets, row level security rules and a report send. Record the bundle identifier, the database backup location and the rollback steps in the change ticket before the production window opens.

Limits to confirm in your environment

An air-gapped Superset build depends on several assumptions that the public documentation does not settle for every version. The six items below are the ones to verify against the exact release you plan to run, in a test network that mirrors your isolation rules.

Map tile, font and asset URLs

Superset pages and charts can load map tiles, web fonts and static assets from external hosts. Before installation, list every URL the chosen version requests from the browser and from server-side rendering, then decide whether each one is mirrored internally or removed. A missing tile server usually fails silently, so check geospatial charts and custom fonts in a fully blocked test network rather than relying on the release notes.

Telemetry and update checks

Confirm whether telemetry or update checks can be fully disabled in the version you run, and which setting controls each one. Do not assume a single flag covers everything. Capture outbound connection attempts from the application host during startup, login, dashboard rendering and an upgrade rehearsal, and keep the results as evidence for your security reviewers.

OAuth and LDAP providers

Superset supports OAuth2 providers, custom OAuth2 servers using the code flow, and LDAP. An OAuth provider that lives on the public internet is an external dependency, so list the identity providers your users need and confirm each one can run on your internal network. Then confirm how group claims map to roles through AUTH_ROLES_MAPPING.

Metadata database versions

The configuration documentation lists supported metadata database versions as PostgreSQL 10 to 17 and MySQL 5.7 and 8.x. Confirm that your internal database image or managed service falls inside that range for the Superset version you select. Check the version list again at upgrade time, because a database that is supported today may fall outside a later release's list.

Operator or Helm path readiness

The Helm chart is marked deprecated in current development documentation, and the Kubernetes Operator is in alpha with a v1alpha1 API whose schemas may change between releases. Decide which path your platform team can support offline, confirm that mirrored chart or operator images are available, and plan for schema changes before any upgrade. Avoid building on the alpha API for a production system without a fallback.

Report rendering without browser downloads

Alerts, reports and thumbnails depend on a headless browser that must exist inside the air-gapped network. Confirm which browser binary your image includes, where it is installed from during the build, and whether it can render pages that reference internal URLs only. Test a scheduled report end to end with no outbound access, including the worker and the internal HTTP path it uses to reach the web server.

Questions buyers ask before running Superset offline

What drives the cost and effort of an air-gapped Superset install?

The biggest drivers are how many database drivers and extensions you need, how many environments must be rebuilt offline, and how much of the stack must be served internally. Each item you cannot fetch from the internet (container images, Python packages, map tiles, fonts, and identity provider metadata) adds a packaging and verification step. Costs fall into two groups. One-time costs cover design, building the offline image set, configuring internal services, and testing. Recurring costs cover re-packaging each upgrade and checking every artifact that crosses the boundary. Ask any provider for a quote that lists each artifact, who builds it, and how it will be verified.

How long does an air-gapped Superset deployment take?

No timeline figure is supplied for this topic, so treat any number you hear with caution. The schedule depends on the number of target environments, whether the metadata database and any caching or worker components are included, how many connectors must be bundled, and how quickly your security team can review and approve media transfers. Your internal approval cycles often set the critical path more than the technical build does. A written scope with milestones should show which steps depend on your reviews, so you can plan around them.

What does our internal team need to provide?

Expect to supply access to the target network, the approved transfer process for moving files across the boundary, and named owners for identity, the metadata database, and the internal registry or package mirror. You will also need to confirm which database engines and drivers analysts must reach, since that decides what goes into the image. Plan for a staff member who can approve the software bill of materials and the checksums for each package. Ask the provider to list these inputs in writing before work starts, along with the reviews they expect from your side.

Can our own team run an offline Superset deployment without outside help?

Yes, if your team already runs containers, Python services and a PostgreSQL or MySQL metadata database, and has a reliable way to move verified artifacts into the isolated network. The harder parts are usually not Superset itself but building a complete offline dependency set, keeping map tiles and fonts internal, and testing upgrades without internet access. Many teams start in-house and bring in a partner for the packaging and testing phase. A written scope helps you decide which steps to keep internal.

How do Superset upgrades differ when the network is offline?

The upgrade steps are the same as online, but every artifact must be rebuilt, scanned, and transferred before you can start. Back up the metadata database, run the database upgrade and init commands in staging first, and read the project's UPDATING.md for breaking changes between versions. Offline, you also need the new image, Python packages, and any browser or font assets bundled and verified in advance. Each version change therefore adds packaging and review time, which is why upgrade cadence should be part of the scope.

Does DeployOpen prepare evidence for a compliance assessment?

DeployOpen prepares systems, controls and evidence for compliance assessments, such as configuration records, artifact verification logs, access settings, and backup and upgrade procedures. DeployOpen does not issue audit reports, attestations or certifications. Independent auditors and certification bodies perform those assessments. Ask your assessor early which evidence they expect, such as software integrity checks for packages carried across an isolated boundary, and include those items in the written scope.

What should be in a written scope before we ask for a quote?

A useful scope lists the Superset version, target environments, database connectors, identity provider, internal services such as map tiles and fonts, the transfer and verification process, the testing plan, and the upgrade process. It should also state what your team provides and what the provider delivers. DeployOpen plans most engagements as fixed scope, with scope, deliverables and timelines agreed in writing before work starts, and provides a quote that follows from that written scope.

How DeployOpen scopes and delivers offline Superset work

DeployOpen delivers offline Superset work under a fixed-scope agreement that is written and accepted before any build starts. The scope names every part of the offline estate: the prebuilt image and its driver set, how map tiles and fonts are served internally, the identity integration (for example, an internal LDAP directory or an OAuth2 server you run), the connections to your analytics databases, the verification tests, and an offline upgrade runbook. Each item carries its own deliverable, so you can see what is covered and what is excluded before you commit. Ask for the scope to state which external endpoints were removed, which were replaced internally, and which the client must still provide, because those answers decide how much of the work is in fact internal.

The work is carried out inside your own environment, whether that is your cloud accounts, data centers or an isolated network. DeployOpen builds the image pipeline, configuration, and runbooks there and documents them so your team can rebuild and operate the platform without us. Ongoing work is handled separately. Optional retainers can cover future Superset upgrades, repeated offline image builds, and regression testing against new releases, which matters because each upgrade on an isolated network repeats the transfer and verification steps. Ask whether the retainer includes that repeat work and how urgent security fixes are carried across the boundary.

DeployOpen prepares the systems, configuration records, test results and change evidence that an assessor will ask for, so your compliance team can show how Superset was built, verified and changed. We do not issue audit reports, attestations or certifications. Independent auditors and certification bodies make those determinations, so confirm early with your assessor which artifacts they expect and in what format. Once the written scope is agreed, the quote follows from it, and the quote should list which items are one-time and which recur.

Apache Superset in air-gapped networks