Docker Development Environment#

Superset's Docker Compose setup supports local development and evaluation (not production). Three distinct Compose files target different use cases 1:

Not production-ready. Docker Compose is designed for single-host use. For HA deployments, use Kubernetes. 2

Services in docker-compose.yml#

The default compose file starts these services:

• superset – Flask app server, launched via docker/docker-bootstrap.sh app 3
• superset-init – One-shot init container that runs docker/docker-init.sh: applies DB migrations, creates the admin user, sets up roles, and optionally loads examples 4
• superset-node – Node container running docker/docker-frontend.sh for webpack builds 5
• superset-worker / superset-worker-beat – Celery workers launched via docker-bootstrap.sh worker/beat 6
• superset-websocket – Async websocket server on port 8080 7
• redis, db (Postgres 16), nginx – Backing services 8

All Superset services share a common x-superset-volumes block that mounts ./docker, ./superset, ./superset-frontend, and ./tests into the container 9, enabling live code reloading.

Frontend Build: superset-node and docker-frontend.sh#

docker/docker-frontend.sh is the entrypoint for the superset-node container. Its behaviour is controlled by two env vars 10:

• BUILD_SUPERSET_FRONTEND_IN_DOCKER=true (default): runs npm install then npm run dev-server inside the container, serving webpack output on port 9000.
• BUILD_SUPERSET_FRONTEND_IN_DOCKER=false: skips the build entirely — you must run npm i && npm run dev on the host yourself (recommended if you have <16 GB RAM) 11.
• NPM_RUN_PRUNE=true: runs npm run prune before install to clear stale node_modules 12.

The npm run dev-server script launches webpack-dev-server in development mode, serving on localhost:9000 13.

Webpack Proxy Configuration#

superset-frontend/webpack.proxy-config.js proxies all non-asset requests from the webpack dev server back to the Flask backend. The backend URL is resolved from the superset environment variable (injected as http://superset:8088 when running in Docker) or defaults to http://localhost:8088 14. HTML responses are intercepted and rewritten via toDevHTML() to replace bundled asset tags with dev-server paths and prefix the page title with [DEV].

Environment Variables#

All services load env from two layered files 15:

Key variables from docker/.env:

Python-level overrides can be placed in docker/pythonpath_dev/superset_config_docker.py (git-ignored); the base config at docker/pythonpath_dev/superset_config.py auto-imports it 16.

Pre-built Release Mode (docker-compose-image-tag.yml)#

The image is pulled from Docker Hub via the TAG env var (default: latest-dev). Use a -dev-suffixed tag (e.g. 5.0.0-dev) because dev builds include psycopg2-binary needed to connect to the bundled Postgres container 17.

Key File Index#