Apache Superset Docker Setup: A Complete Guide to the superset-sh Workspace Configuration

The Apache Superset Docker setup in the superset-sh repository uses Docker Compose orchestrated through .superset/config.json to automatically manage workspace lifecycle, including an Electric SQL sidecar container for real-time data sync.

The superset-sh/superset repository provides a declarative, workspace-aware Docker environment that simplifies local development. Instead of manual container management, the Superset CLI reads configuration files to automatically spin up services, run database migrations, and clean up resources when you switch contexts. This guide explains the exact mechanics of the Apache Superset Docker setup based on the source code implementation.

Core Components of the Apache Superset Docker Setup

The Docker workflow is distributed across four key files that handle configuration, execution, and cleanup.

Configuration Layer (.superset/config.json)

The entry point for the Apache Superset Docker setup is .superset/config.json at the repository root. This JSON file declares the default setup and teardown command arrays that the Superset CLI executes for every workspace.

The default configuration includes Docker Compose commands:

{
  "setup": [
    "docker-compose up -d",
    "bun run db:migrate"
  ],
  "teardown": [
    "docker-compose down -v"
  ]
}

Setup Orchestration (.superset/lib/setup/steps.sh)

The file .superset/lib/setup/steps.sh contains the bash functions that validate and execute the Docker environment. It performs two critical Docker-related tasks:

1. Dependency verification: The step_check_dependencies function verifies that the docker CLI is available in the system PATH before attempting any container operations.

2. Electric SQL sidecar: Lines 260-280 automatically start an Electric SQL container using the electricsql/electric:latest image. This container is essential for real-time data synchronization features in the Superset development environment.

docker run -d \
  --name superset-electric-<workspace-id> \
  -p ${ELECTRIC_PORT}:3000 \
  -e DATABASE_URL="${DIRECT_URL}" \
  -e ELECTRIC_SECRET="${ELECTRIC_SECRET}" \
  electricsql/electric:latest

Teardown Cleanup (.superset/lib/teardown/steps.sh)

When a workspace is deleted, .superset/lib/teardown/steps.sh executes the cleanup sequence. Lines 48-60 stop and remove the Electric SQL container, while the standard docker-compose down -v command (defined in the config JSON) removes the main service containers and their volumes.

How the Docker Workspace Lifecycle Works

The Apache Superset Docker setup follows a strict lifecycle tied to workspace creation and deletion:

1. Workspace creation: The Superset CLI reads .superset/config.json and executes the setup array sequentially. First, docker-compose up -d launches your project-defined services (PostgreSQL, Redis, etc.). Then, bun run db:migrate executes database migrations against the running containers.

2. Sidecar initialization: Simultaneously, the setup script starts the Electric SQL container on the port specified by the ELECTRIC_PORT environment variable, proxying it through a local Caddy reverse-proxy.

3. Workspace deletion: The CLI runs the teardown array. The docker-compose down -v command stops all compose services and deletes named volumes, while the teardown script explicitly stops the Electric SQL container to prevent orphaned processes.

Customizing Your Docker Configuration

The superset-sh repository allows developers to override the default Apache Superset Docker setup without modifying committed files.

User Overrides

Place a custom configuration at ~/.superset/projects/<project-id>/config.json to completely replace the default Docker commands for a specific project. This is useful when you need different compose files or additional pre-setup scripts.

Local Extensions

Create .superset/config.local.json in your workspace to extend the default configuration. This file supports before and after hooks:

{
  "setup": {
    "before": ["echo 'Running custom pre-setup script'"],
    "after": ["echo 'Setup complete'"]
  }
}

The final command order becomes: before → docker-compose up -d → bun run db:migrate → after.

Example Docker Compose Configuration

While the superset-sh repository does not include a docker-compose.yml file (developers provide their own), here is a minimal configuration compatible with the Apache Superset Docker setup:

# docker-compose.yml (placed at the repo root)

version: "3.9"
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: superset
      POSTGRES_DB: superset
    ports: ["5432:5432"]
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7
    ports: ["6379:6379"]

  superset:
    image: apache/superset:latest
    env_file: .env
    ports: ["8088:8088"]
    depends_on: [postgres, redis]

volumes:
  postgres_data:

Summary

• The Apache Superset Docker setup in superset-sh uses Docker Compose orchestrated through .superset/config.json to manage workspace lifecycle.
• Setup scripts (.superset/lib/setup/steps.sh) verify Docker availability and automatically launch an Electric SQL sidecar container for real-time sync.
• Teardown scripts (.superset/lib/teardown/steps.sh) ensure complete cleanup of containers and volumes when workspaces are deleted.
• Developers can override default Docker commands using ~/.superset/projects/<project-id>/config.json or extend them with .superset/config.local.json.

Frequently Asked Questions

What is the default Docker setup command in superset-sh?

The default setup command is docker-compose up -d, defined in .superset/config.json. This command launches all services defined in your project's docker-compose.yml file in detached mode, followed automatically by bun run db:migrate to initialize the database schema.

How does superset-sh handle Docker container cleanup?

Cleanup is handled by the teardown script at .superset/lib/teardown/steps.sh and the teardown array in the config file. The default docker-compose down -v command stops all compose services and deletes their named volumes, while the script explicitly stops and removes the Electric SQL container to prevent orphaned processes.

Can I use a custom docker-compose.yml with superset-sh?

Yes. The superset-sh repository does not include a docker-compose.yml file; developers must provide their own at the workspace root. You can customize service definitions, environment variables, and ports. The Superset CLI will automatically detect and use your file when executing the docker-compose up -d command from the config.

What is the Electric SQL container used for in Superset?

The Electric SQL container (electricsql/electric:latest) is a required side-service started automatically by .superset/lib/setup/steps.sh. It provides real-time data synchronization capabilities for the development environment, running on a dedicated port and proxied through a local Caddy reverse-proxy. The container is stopped and removed during workspace teardown to ensure clean resource management.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}