Running Apache Superset with Docker Compose in production: where it fits
Docker Compose suits evaluation and small internal use of Apache Superset, and it does not make the decisions a production deployment needs. If your team has a working Compose stack and must decide whether it can carry real dashboards for business users, treat the stack as a starting point rather than a finished production design. The default stack brings up the application, a PostgreSQL metadata database, Redis, and Celery worker and beat processes, but it leaves the operational choices to you. The Superset architecture documentation names four components: the Flask and React application, the metadata database, an optional caching layer, and optional Celery worker and beat processes. Alerts and reports, async queries and dashboard thumbnails depend on the caching layer and workers, so a stack that runs them must keep those services healthy as well as the web tier. The Docker Compose guide states that operators must still back up the metadata database and extend the image with their own database drivers and settings. Both tasks fall to your team, and neither is handled by the file you start with.
Before you accept the Compose stack for production, confirm several points in writing. Check whether the metadata database is an external, managed or separately operated PostgreSQL or MySQL instance with a tested backup and restore path, since the architecture documentation does not recommend the Compose PostgreSQL container for production. Confirm that your SECRET_KEY is set from a secret store and not from the example file. Confirm who owns the custom image, how it is rebuilt when Superset releases a new version, and where TLS terminates. Ask the vendor or your platform team which of these responsibilities they will carry after go-live.
The answers decide whether Compose remains viable. If the team needs high availability, several web replicas behind a load balancer, managed backups and a routine upgrade process run by a regular release cycle, a single Compose host usually becomes the constraint, and the next step is a platform such as Kubernetes. The Superset Helm chart and the newer Kubernetes Operator each carry their own maturity notes, so verify their status before you choose. Making that call early avoids rebuilding the deployment after dashboards are already in use.
Which production gaps Compose leaves open
The Compose file starts a PostgreSQL container alongside Superset, Redis, and the Celery worker and beat processes. The Superset docs say the bundled database suits trying the stack, not production, and that operators must still back up the metadata database themselves. That database holds dashboards, charts, users, roles and data source connections, so it is the state you have to recover.
- Move the database out of Compose. Point the metadata connection at a PostgreSQL or MySQL service you run or buy, using a version from the supported range (PostgreSQL 10 to 17, MySQL 5.7 and 8.x).
- Schedule backups outside the containers. Dump or snapshot the metadata database with the service's own tooling, and store copies away from the host running Compose.
- Test restores. A backup that has never been restored is unproven. Restore it into a separate instance and open a dashboard to confirm it works.
- Keep credentials out of the file. Supply the database password through environment variables or a secrets store, not through a Compose file committed to Git.
Confirm who owns the database service, how long backups are retained and how quickly the business expects service to return after a failure.
The published Superset image does not carry every database driver you need, so the installation docs direct operators to extend it. Compose runs whatever image tag you reference, which means the driver set, Python packages and optional feature dependencies are decided in your Dockerfile and build pipeline, not in the Compose file. Build the image once, give it a tag you can name and reference that same tag in every environment.
- Add only the drivers your sources need. Install a driver for each warehouse or database you connect, and check its version against what the source database supports.
- Pin every version. Use explicit tags for the base image and each added package so a rebuild cannot change behavior without a visible change to the build file.
- Build into a registry you control. Push the image to a registry your organization operates and reference an immutable tag or digest where the registry supports it.
- Scan before deployment. Run an image vulnerability scan in the build pipeline and keep the result with the release record.
- Confirm optional components. If you plan scheduled reports or thumbnails, check whether your image includes the browser components those features need, because the Compose file does not add them.
Confirm which drivers and optional components the image contains, and who rebuilds it when the base image receives a security update.
Superset needs a SECRET_KEY supplied before it starts, a requirement added in version 2.1.0. Example Compose files often include a placeholder value, and teams sometimes type a real value directly into the YAML. That value then lands in version control and in every copy of the stack. Superset uses this key to protect sessions and sensitive values it stores, so a leaked key has consequences beyond the login page.
- Generate a unique key per environment. Create each key with a strong random generator and deliver it at runtime from a secrets manager or an injected environment variable.
- Remove placeholders from the repository. Replace example values in the tracked files and search the Git history for any key that was committed.
- Plan rotation with PREVIOUS_SECRET_KEY. Superset supports rotating the key through this setting. Schedule the change and keep the old key available for the transition described in the configuration docs.
- Keep the key with the database backup. Store the key where your recovery process can reach it. A restored database without its matching key cannot read the values it encrypted.
Confirm where each key is stored, who can read it and whether the rotation procedure has been tested against a copy of the environment.
The Compose stack exposes Superset on a published port over plain HTTP. Browser sessions, login cookies and API clients need TLS, and the proxy in front of Superset has to pass the original scheme and host to the application. Check whether the Compose version you deploy includes any TLS termination, since your certificate authority, DNS and network path are outside what the file can provide.
- Terminate TLS at a proxy or load balancer. Use a certificate from your certificate authority and keep the Superset port reachable only from the proxy.
- Configure forwarded headers. Enable the proxy handling in the configuration docs so Superset trusts forwarded headers only from known proxy addresses, which keeps redirects and secure cookies correct.
- Set browser security headers at one layer. Decide whether HSTS and other headers come from the proxy or from Superset, and verify the response headers after each change.
- Route async and report traffic. If you use async queries, confirm that WebSocket paths reach the service and that report workers can reach the web application over an internal address.
- Limit exposed internal ports. Keep PostgreSQL, Redis and worker ports on an internal network, and do not publish them on the host interface.
Confirm the certificate lifecycle, the trusted proxy addresses and the internal path that report workers use before you test a login through the public name.
Upgrading a Compose stack changes the metadata schema as well as the image tag, so an image pull alone is not an upgrade. The upgrade guide asks you to back up the metadata database, run the database upgrade and initialization commands and test in staging first. Each release can also contain breaking changes listed in UPDATING.md, so the plan starts by reading that file for every version between your current release and your target.
- Back up before the image changes. Take a metadata database backup and confirm you can restore it before pulling the new image.
- Run the migration steps in order. Execute the database upgrade and initialization commands from the upgrade guide against the staging copy first.
- Read the breaking changes. Review UPDATING.md for each version you cross and record any configuration changes it requires.
- Keep the previous image available. Retain the prior image tag so you can roll back the application, and plan for the database migration, which may not reverse cleanly.
- Check release status. Confirm whether the target is a stable release or a pre-release listed on the release page before you schedule around it.
Confirm the rollback path with your database owner and the change window your users will accept before you schedule the upgrade.
Deployment options and when each fits
This table compares four ways to run Superset: Compose with the bundled PostgreSQL container, Compose against an external metadata database, a PyPI install on a VM, and Kubernetes. Read each row against your team's skills and who will own backups and upgrades. The main takeaway is that the bundled Compose database suits evaluation, while production needs an external, backed-up metadata database whichever option you choose.
| Option | Fit and main trade-off | Team skills and failure handling | Backup and upgrade ownership |
|---|---|---|---|
| Compose with bundled PostgreSQL | Fastest path to a running stack, but the project does not recommend its PostgreSQL container for production | Docker and Compose knowledge; restarts and volume recovery are your job | You back up the metadata database and extend the image yourself |
| Compose with external PostgreSQL or MySQL | Keeps the metadata database on a service you already operate, the common step up from the bundled container | Docker plus database administration; confirm the database version is within the supported range | Database team or provider owns backups; you own the upgrade sequence and staging tests |
| PyPI install on a VM | Fits teams that run Python services on Linux and want no container layer | Python packaging, OS libraries, process supervision; you add Redis and Celery yourself for full features | You back up the metadata database and manage each upgrade in place |
| Kubernetes with the Helm chart | The chart is marked deprecated in current development docs, so confirm its status before choosing it for new work | Cluster operations, Helm, ingress and secrets management; failure handling depends on cluster design | Platform team owns cluster upgrades; you own Superset chart and release changes |
| Kubernetes Superset Operator | Newer path that the current docs point new deployments toward, but it is alpha with a v1alpha1 API that may change between releases | Kubernetes operator skills plus tolerance for schema changes between releases | Plan for manifest rewrites on upgrade; confirm backup and restore steps with the project |
Moving a Compose evaluation stack toward production
This sequence turns a Docker Compose evaluation into a stack with a pinned version, an external metadata database, managed secrets, TLS and tested backups. Each step closes with a check the team can repeat before users depend on the stack.
Pin the Superset version and review releases
The platform team chooses one Superset version and records it in the build and deployment files, so no step pulls a floating tag. Before choosing, they read the release list on the project's GitHub releases page and check the PyPI package history for the candidate release, noting that pre-release tags such as release candidates should not be used for production. Done means the chosen version appears in version control with a short note on why it was selected and which release notes were reviewed.
Build a custom image with required drivers
The team extends the official Superset image with the database drivers their analysts need, and adds any other packages their configuration depends on. The Compose file then references this image by a versioned tag instead of building from the default. Done means the image builds from a clean checkout, the driver imports succeed inside a running container, and the image tag is stored in the same repository as the Compose file.
Set a SECRET_KEY outside the image
The security or platform engineer generates a unique SECRET_KEY and injects it at runtime from a secret store or protected environment file, so it never lands in the image or in Git. Superset requires a user-specified key to start, so the stack will fail to boot without it, which makes the check straightforward. Done means the application starts with the injected key, the key is absent from the repository and image layers, and the team has recorded where the key is held and who can read it.
Point the metadata database at an external instance
The database team provisions a PostgreSQL or MySQL instance that Superset is tested with, using a version within the range listed in the configuration documentation, and removes the Compose PostgreSQL container from the production file. The connection string is supplied through secrets. Done means Superset connects to the external host,
superset db upgradecompletes against it, and the database version is confirmed as supported in the project's configuration documentation.Configure Redis and Celery workers
The team confirms that Redis, the Celery worker and the Celery beat service run as separate, supervised services with their own configuration, since alerts and reports, async queries and dashboard thumbnails depend on them. Connection details for the caching layer come from the same secret source. Done means a test async query returns results through the worker, a scheduled test task runs on the beat schedule, and restarting the worker does not lose queued work the team expects to keep.
Place a reverse proxy with TLS in front
The network or platform team puts a reverse proxy or cloud load balancer in front of the web service, terminates TLS there with certificates from the organization's authority, and configures the proxy settings Superset expects. The proxy also needs routing for WebSocket connections used by async queries. Done means the application loads only over HTTPS, the browser shows a valid certificate chain, and an async query completes through the proxy path.
Set up and test metadata database backups
The database owner schedules backups of the external metadata database and stores copies outside the host that runs Superset. A restore is then performed into a separate instance, and the team checks that users, dashboards and saved configuration appear. Done means a restore from the most recent backup has been completed on a test instance and verified by opening a known dashboard, and the restore steps are written down with the owner named.
Rehearse an upgrade in staging
Before any production change, the team applies the target Superset version to a staging copy with a restored database, following the upgrade guide. They back up the database first, run
superset db upgradeandsuperset init, and review UPDATING.md for breaking changes between the current and target versions. Done means staging runs the new version with no migration errors, key dashboards and alerts behave as before, and the team has a written rollback plan tied to the pre-upgrade backup.
Security risks in a Compose stack that reaches production
A Compose file that works on one host can carry risks that a production stack cannot accept. The cards below cover the secrets, network exposure, credentials, authentication, patching and data handling that connect the Superset containers to your databases and your users.
SECRET_KEY and rotation
Superset requires a user-specified SECRET_KEY to start, and the value signs session data. Compose stacks often ship a placeholder or commit the value to the repository. Store it in a secret manager or an environment file outside Git, and confirm who can read it. When you rotate it, use PREVIOUS_SECRET_KEY so existing sessions keep working during the change, then remove the old value once the rotation is complete.
Exposed ports and network segmentation
The default Compose file publishes ports on the host, and the metadata database and Redis may be reachable from the same network as the web tier. Publish only the reverse proxy port, keep PostgreSQL and Redis on an internal Docker network, and confirm with docker compose ps and a scan from outside the host. Ask whether your hosting environment adds its own firewall rules that override Docker's port publishing.
Metadata and warehouse credentials
The metadata database holds Superset's users, dashboards and database connection details, so its password is a high-value target. Each warehouse connection should use a dedicated read-only account scoped to the schemas its dashboards need, not a personal or administrator login. Rotate these passwords on a schedule you can document, and keep them out of superset_config.py and image layers.
Authentication source and role mapping
Superset's login can come from OAuth2 providers, LDAP or the built-in database users. Choosing a source decides who can sign in after an employee leaves. Map identity provider groups to Superset roles with AUTH_ROLES_MAPPING, and test that a removed group loses access on the next sign-in. Confirm whether local database accounts remain enabled as a fallback and who controls them.
Host and image patching
Compose pins images by tag, and nothing updates them automatically. The host operating system, Docker Engine, the Superset image, PostgreSQL and Redis each have their own patch cycle. Record the versions in use, subscribe to the project's release notes, and plan a staging test before each upgrade. Read the upgrade notes for breaking changes before you move a tag forward.
Logs and backup access
Container logs, the metadata database dump and Docker volumes can each expose user names, query text and connection details. Restrict who can read docker logs, the volume paths on the host and backup storage, and encrypt backups at rest. Ask who holds restore rights and whether restores are logged, because a backup copy of the metadata database is as sensitive as the live system.
Questions teams ask before running Superset on Compose
How much effort does it take to move Superset off the default Compose stack?
Moving off the default stack is mainly a set of changes to the metadata database, the image, secrets, TLS and the backup routine, so the effort depends on how many of those are already in place. The default Compose file uses a PostgreSQL container for metadata, which the Superset architecture documentation does not recommend for production, so you will usually replace it with a managed or separately operated PostgreSQL or MySQL instance. Supported metadata versions are PostgreSQL 10 to 17 and MySQL 5.7 and 8.x, so confirm your target version against that list. Effort rises with the number of database drivers you need, the number of environments, whether you run alerts, reports and async queries with Redis and Celery, and how much of the configuration lives in environment variables versus superset_config.py. Ask any partner to break the work down by these items.
Can our own platform team do this work internally?
Often yes, if your team already operates containers, managed databases, a reverse proxy and an identity provider, and has someone who can read Superset's upgrade notes. The skills that matter most are database operations, secret handling, certificate management and release testing, not Superset-specific knowledge alone. Check three things before deciding: whether you have a staging environment that mirrors production, whether someone owns the backup and restore test, and whether the people on call know how Celery workers and beat behave when Redis is unavailable. If any of these are missing, an implementation partner can build them under a written scope, and you keep the operating runbook. Compare the internal estimate against the same checklist so the two options are measured the same way.
What does the work need from our side before it starts?
Expect to provide access and decisions rather than hands-on build time alone. The usual inputs are a metadata database host or managed instance with credentials, DNS names for the Superset and any worker-facing endpoints, TLS certificates or the ability to issue them from your certificate authority, the identity provider details if you use OAuth2, OIDC or LDAP, a staging environment, and a named owner who can approve the production cut-over. You will also need to decide where secrets live, since SECRET_KEY must be set before Superset starts. Confirm the exact list with your own network and security teams, because firewall rules, proxy policies and DNS change requests often have longer lead times than the software work itself.
How long does the migration take, and what changes the timeline?
No duration figure is supplied for this work, so treat any number you hear as a claim to verify against a written scope. The timeline is driven by the number of components in scope (web application only, or web application plus Redis, Celery worker and beat), the metadata database migration path, the count of custom database drivers and images, identity provider integration, and how many approval cycles your change process requires. Staging validation and a rehearsed restore usually take longer than the configuration changes. Ask for milestones tied to each component and a list of the decisions that must be made before build starts.
At what point is Kubernetes a better choice than Compose?
Compose suits a single host or a small set of hosts with a clear owner, a managed metadata database and a stable workload. Kubernetes becomes the better option when you already run a cluster platform, need scheduling across several nodes, want standard rolling updates and health probes, or must follow platform-wide policies for networking and secrets. Be aware that the Superset 6.1.0 documentation describes installs with the official Helm chart, while the current development documentation marks that chart as deprecated and points new deployments to the Apache Superset Kubernetes Operator. The operator is in alpha with a v1alpha1 API whose schemas may change between releases, so plan for changes to your manifests during upgrades.
What happens to backups and upgrades when we run Superset on Compose?
Compose does not back up your data for you. The Superset docs state that operators must still back up the metadata database, so the backup schedule, retention and restore test sit with your team or your partner. Before each upgrade, the Superset upgrade documentation says to back up the metadata database, run superset db upgrade and superset init, test in staging first, and check UPDATING.md for breaking changes between versions. Keep the Compose file, image tag and superset_config.py in version control so you can roll back to a known state. Confirm your restore time objective and recovery point objective with your own risk owners, since neither is provided here.
Does the Compose stack meet our compliance and security requirements?
The Compose file alone does not settle compliance or security. It is a starting point that lacks a production metadata database, a defined secret strategy, TLS termination and an upgrade process, and each of these must be designed and evidenced. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications; independent auditors and certification bodies do that. Ask your auditor which controls they will test and map those to your Superset configuration before the build starts.
Limits to confirm in your environment
Docker Compose can run a Superset stack, but several decisions decide whether it fits your production needs. The cards below cover the release, database, host, orchestration and image choices to confirm before you build. Each one is a point where a Compose setup can stop matching what your organization requires.
Release and pre-release status
Confirm which Superset release you will run and whether it is a stable release or a pre-release. The release list on GitHub shows 7.0.0rc2 as a pre-release dated October 16, 2026, so an rc tag should not reach production. Pin the exact version in your Compose file and record the upgrade path before the first deployment. Check the release notes and UPDATING.md before any version change.
Metadata database version support
The Compose file ships a PostgreSQL container, but the project does not recommend that container for production. Plan an external PostgreSQL or MySQL service and confirm that its version falls within the supported range in the configuration documentation. Ask your database team who backs it up, how restores are tested, and where the data lives. Compose does not provide those controls on its own.
Single host availability
A Compose stack normally runs on one host, so a host failure takes down the web app, workers and cache together. Compare the outage you can accept for dashboards, scheduled reports and async queries with what one VM provides. Confirm who patches the host, how it is restored, and whether a second host or a managed database changes that answer. Document the result before you sign off.
Kubernetes operator maturity
If you expect to move to Kubernetes later, confirm the status of the Apache Superset Kubernetes Operator before you plan around it. The project documents it as alpha, with a v1alpha1 API whose custom resource schemas may change between releases. Do not treat it as a stable target for a multi-year plan. Ask the team that will own it how they will handle breaking changes.
Helm chart deprecation
The 6.1.0 documentation describes Kubernetes installs with the official Helm chart, but current development docs mark that chart as deprecated and point new deployments to the operator. Decide which path your platform team will follow before you write Kubernetes manifests or Helm values. Any values you carry over from a Compose setup should be reviewed against the release you actually run.
Custom image for drivers and identity
The stock image does not include every database driver or identity library your environment needs. List the warehouses you will query and the identity provider you will use, then confirm which Python packages each requires. Build a custom image that adds them, pin the base version, and scan the result before deployment. Keep the build recipe in version control so the image can be rebuilt during an upgrade.
When Compose stops being enough and Kubernetes starts to make sense
Move off Docker Compose when the cost of running it by hand starts to exceed the cost of a platform. The clearest signals are several environments that must receive the same release through the same process, web and Celery worker capacity that needs to scale independently of each other, availability requirements that a single Compose host cannot meet, and an existing cluster platform team that already runs deployment, monitoring and backups for other services. Any one of these can justify a move. Two or more usually do. Before deciding, write down which signals apply to you and who would own the cluster, upgrades and on-call for Superset.
The Kubernetes path has a maturity problem you must plan around. The Superset 6.1.0 documentation describes installs with the official Helm chart, but the current development documentation marks that chart as deprecated and points new deployments to the Apache Superset Kubernetes Operator. The Operator is built with the Go Operator SDK and is in alpha, with a v1alpha1 API whose custom resource schemas may change between releases. Confirm the current guidance in the Superset Kubernetes installation documentation before you pick a method, and ask whether your upgrade process can absorb schema changes on a release you did not choose.
If you stay on Compose for now, design it so the move is cheap later. Keep the metadata database external and backed up, keep superset_config.py and the SECRET_KEY out of the image, and keep the custom image reproducible. Those three choices carry over to any orchestrator. A move to Kubernetes then changes the deployment layer, not the data or configuration you have already protected. Ask the platform team to test a staging install on the Operator and the Helm chart side by side, and record which one they would support for the next two years.
How DeployOpen scopes and delivers a production Superset stack
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, so a Superset stack meant for production is designed around your data, identity and network rules. Each engagement starts with a written scope that states what the Compose topology replaces, what it keeps, and what moves to another platform.
How we scope
- Confirm whether Docker Compose fits your availability, backup and staffing needs before any build starts.
- Name the external PostgreSQL or MySQL metadata database, its version and where its backups are held.
- Record which optional Redis and Celery components, alerts, reports and async queries are required.
How we build
- Build a custom image with your database drivers and pinned versions instead of running the default container.
- Set SECRET_KEY, TLS termination and proxy settings from your secret store, not from files in the repository.
- Test each upgrade in staging first, following the project's upgrade steps and UPDATING.md breaking change notes.
How we hand over
- Deliver the Compose files, image build definition, configuration and a runbook for restore and upgrade.
- Document the criteria that would trigger a move from Compose to Kubernetes, with the Helm chart and operator status noted.
- Walk your platform and security teams through backup restore tests and the evidence they should keep.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer after handover, scoped in writing.
- Review each new Superset release notes and configuration changes against your deployment before rollout.
- Confirm with your team which parts of ongoing support you want, since scope and cost follow the written agreement.
