TVL Managed Superset
Get started

Install Apache Superset with Docker: Complete 2026 Guide

Install Apache Superset with Docker and docker-compose: prerequisites, configuration, data persistence, security, and production best practices.

· Tuvalu Tech OÜ

Docker is today the fastest way to start an Apache Superset instance locally or on a server. In 2026, the official apache/superset image is mature, well documented, and used by most data teams getting started. This article details step by step the installation with Docker and docker-compose, volume and secrets configuration, and the adjustments needed to move from POC to production.

1. Why Docker for Apache Superset

Before Docker, installing Superset required Python 3.10, system packages (libssl, libffi, build-essential), a PostgreSQL database, Redis, Celery, and manual resolution of each connector's dependencies (psycopg, mysqlclient, snowflake-connector-python). With Docker, all this stack is encapsulated in a reproducible, versioned image, compatible with any Linux or macOS distribution.

If you want to avoid this friction, TVL Managed Superset deploys a ready-to-use instance in less than 3 minutes, with PostgreSQL, Redis, and the Celery worker pre-configured. For a self-hosted installation, this guide is the simplest path.

2. Prerequisites

  • A Linux, macOS, or Windows machine with WSL2.
  • Docker Engine 20.10+ and docker-compose v2 (integrated into recent Docker CLI).
  • At least 4 GB available RAM (8 GB recommended in production).
  • 4 GB of disk space for images and initial volumes.
  • Ports 8088 (Superset UI) and 5432 (Postgres) free locally.

3. Quick start with the official repo

The fastest way is to clone the official apache/superset repo, which provides a ready-to-use docker-compose.yml. 

git clone --depth=1 https://github.com/apache/superset.git
cd superset
docker compose -f docker-compose-non-dev.yml pull
docker compose -f docker-compose-non-dev.yml up -d

The -non-dev argument loads the latest stable version. Initial startup takes 2 to 5 minutes (DB initialization, admin creation, migrations). Once done, the UI is accessible at http://localhost:8088, default login admin / password admin.

First rule: change this password immediately via Settings → List Users → Edit.

4. Components deployed by the compose

ServiceRolePort
supersetWeb app (gunicorn + Flask)8088
superset-initOne-shot job: DB migrations, admin creation, examples seed—
superset-workerCelery worker for async queries, alerts, reports—
superset-worker-beatScheduler for planned tasks—
dbPostgreSQL for Superset metadata5432
redisCache + Celery broker6379

5. Customize the configuration

Superset reads environment variables and a superset_config.py file. For a durable install, create a ./docker/pythonpath_dev/ (or ./config/) folder with your own superset_config.py: 

# superset_config.py
import os

SECRET_KEY = os.environ['SUPERSET_SECRET_KEY']
SQLALCHEMY_DATABASE_URI = os.environ['SQLALCHEMY_DATABASE_URI']

# Redis cache
CACHE_CONFIG = {
    'CACHE_TYPE': 'RedisCache',
    'CACHE_DEFAULT_TIMEOUT': 600,
    'CACHE_KEY_PREFIX': 'superset_',
    'CACHE_REDIS_URL': 'redis://redis:6379/1',
}
DATA_CACHE_CONFIG = CACHE_CONFIG

# Feature flags
FEATURE_FLAGS = {
    'EMBEDDED_SUPERSET': True,
    'ALERT_REPORTS': True,
    'DASHBOARD_RBAC': True,
}

# Mailer
SMTP_HOST = os.environ.get('SMTP_HOST', 'localhost')
SMTP_PORT = int(os.environ.get('SMTP_PORT', 25))
SMTP_STARTTLS = True
SMTP_SSL = False
SMTP_USER = os.environ.get('SMTP_USER')
SMTP_PASSWORD = os.environ.get('SMTP_PASSWORD')
SMTP_MAIL_FROM = 'superset@example.com'

And mount this file as a volume in the superset service of the compose:

services:
  superset:
    image: apache/superset:5.0.0
    volumes:
      - ./config/superset_config.py:/app/pythonpath/superset_config.py:ro
    environment:
      SUPERSET_CONFIG_PATH: /app/pythonpath/superset_config.py
      SUPERSET_SECRET_KEY: ${SUPERSET_SECRET_KEY}

6. Generate a strong SECRET_KEY

The SECRET_KEY signs Flask sessions and tokens. Must be long, random, stored as a secret. Generate once:

openssl rand -base64 42
# or
python -c "import secrets; print(secrets.token_urlsafe(42))"

Place in an uncommitted .env file (in .gitignore):

SUPERSET_SECRET_KEY=<your_42+_char_key>
SQLALCHEMY_DATABASE_URI=postgresql+psycopg2://superset:superset@db:5432/superset

7. Data persistence

By default, the official compose uses named Docker volumes. Fine locally but do not forget to configure on server migration or upgrade. Three critical volumes:

  • db_home: PostgreSQL data (Superset metadata, dashboards, charts).
  • redis: cache and Celery state (recreatable without functional loss).
  • superset_home: ~/.superset, may contain generated files.

For durable backups, mount these volumes to a known host path and include them in your backup strategy. See our managed vs self-hosted comparison for the cost calculation of a robust backup strategy.

8. Install additional connectors

The official image includes Postgres, MySQL, SQLite. For ClickHouse, Snowflake, BigQuery, etc., either extend the image or use a bootstrap script. Clean method via derived Dockerfile:

FROM apache/superset:5.0.0

USER root
RUN pip install --no-cache-dir \
      clickhouse-connect \
      snowflake-sqlalchemy \
      sqlalchemy-bigquery \
      pymssql

USER superset

Then build your local image:

docker build -t my-superset:5.0.0 .

And replace the official image with yours in the compose. This configuration is automatically managed by TVL Managed Superset, which pre-installs the most common connectors.

9. Update the Superset version

To move from one version to another:

  1. Backup the PostgreSQL database: docker exec -t db pg_dump -U superset superset > backup.sql.
  2. Bump the version in docker-compose.yml: image: apache/superset:5.0.0.
  3. docker compose pull && docker compose up -d.
  4. The superset-init service automatically applies Alembic migrations.
  5. Check logs: docker compose logs -f superset-init.

Before any production upgrade, read the official release notes — some versions require manual steps.

10. Moving from compose to production

The official docker-compose-non-dev.yml is not designed for production. For production, several adjustments:

  • Externalize PostgreSQL (RDS, OVHcloud managed DB, Supabase).
  • Externalize Redis or use a managed cluster.
  • Replace the compose's db and redis with external hosts.
  • Put the application behind a reverse proxy with TLS (Caddy, Traefik, Nginx).
  • Configure SSO (OIDC, SAML, LDAP).
  • Enable log centralization (Loki, ELK).
  • Monitor (Prometheus exporter, healthchecks).
  • Backup PostgreSQL automatically.

For larger-scale deployment, consider Kubernetes rather than docker-compose: see our Kubernetes deployment guide.

11. Minimum production security

  1. Change the default admin password.
  2. Disable open registration: PUBLIC_ROLE_LIKE_GAMMA = False.
  3. Enable SSO and disable the local login form.
  4. HTTPS mandatory: reverse proxy with Let's Encrypt certificate.
  5. Security headers: TALISMAN_CONFIG with CSP, HSTS, X-Content-Type-Options.
  6. Isolated network: no direct exposure of Postgres or Redis from the Internet.
  7. Regular SECRET_KEY rotation (with session re-signing procedure).

See our Apache Superset hardening checklist for full coverage.

12. Troubleshooting: common errors

"database is uninitialized and superuser password is not specified"

Missing POSTGRES_PASSWORD variable in the db service environment. Add to .env or directly in compose.

The Celery worker processes no tasks

Check Redis connectivity from the worker (docker exec superset-worker redis-cli -h redis ping) and the BROKER_URL in config.

502 error behind Nginx on first call

Superset uses long timeouts on heavy queries. Increase proxy_read_timeout to 300s on Nginx side and SUPERSET_WEBSERVER_TIMEOUT to 300 on Superset side.

"No module named 'psycopg2'"

On some official image versions, the PostgreSQL driver isn't pre-installed in the venv. Extend the image to add psycopg2-binary via uv pip install (not pip install which may write to the wrong Python).

FAQ — Apache Superset Docker

Which image version to use?

Always pin to an explicit version (apache/superset:5.0.0) rather than latest. Avoids bad surprises on docker pull.

Can SQLite be used instead of PostgreSQL?

For a POC yes. For prod, no — SQLite doesn't support concurrency and isn't recommended by official documentation.

Does the image work on ARM (Apple Silicon, Raspberry Pi)?

Yes, since Superset 3.0, multi-arch linux/arm64 images are published. On Mac M1/M2/M3, no special configuration needed.

How many concurrent users can a container serve?

With default config (4 gunicorn workers), an instance can serve 50-100 concurrent active users on moderate dashboards. Beyond, scale horizontally (multiple Superset containers behind a load balancer). See our article on Superset load balancing.

Conclusion

Docker remains in 2026 the simplest way to start an Apache Superset instance, experiment, and even industrialize a small deployment. For serious production (high availability, backups, transparent updates), the operational effort remains significant and often justifies switching to a managed service.

Want the benefits of Apache Superset without the friction of installation and maintenance? Deploy your instance in 3 clicks with TVL Managed Superset, hosted in Europe (OVHcloud, Roubaix, France). For more, see our articles on Kubernetes deployment and Apache Superset production checklist.