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

> Master the Apache Superset Docker setup with superset-sh. This guide details workspace configuration and Electric SQL sidecar integration for seamless data sync.

- Repository: [Superset/superset](https://github.com/superset-sh/superset)
- Tags: how-to-guide
- Published: 2026-03-08

---

**The Apache Superset Docker setup in the superset-sh repository uses Docker Compose orchestrated through [`.superset/config.json`](https://github.com/superset-sh/superset/blob/main/.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`](https://github.com/superset-sh/superset/blob/main/.superset/config.json))

The entry point for the Apache Superset Docker setup is [`.superset/config.json`](https://github.com/superset-sh/superset/blob/main/.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:

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

```

### Setup Orchestration ([`.superset/lib/setup/steps.sh`](https://github.com/superset-sh/superset/blob/main/.superset/lib/setup/steps.sh))

The file [`.superset/lib/setup/steps.sh`](https://github.com/superset-sh/superset/blob/main/.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.

```bash
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`](https://github.com/superset-sh/superset/blob/main/.superset/lib/teardown/steps.sh))

When a workspace is deleted, [`.superset/lib/teardown/steps.sh`](https://github.com/superset-sh/superset/blob/main/.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`](https://github.com/superset-sh/superset/blob/main/.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`](https://github.com/superset-sh/superset/blob/main/.superset/config.local.json) in your workspace to extend the default configuration. This file supports `before` and `after` hooks:

```json
{
  "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`](https://github.com/superset-sh/superset/blob/main/docker-compose.yml) file (developers provide their own), here is a minimal configuration compatible with the Apache Superset Docker setup:

```yaml

# 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`](https://github.com/superset-sh/superset/blob/main/.superset/config.json) to manage workspace lifecycle.
- **Setup scripts** ([`.superset/lib/setup/steps.sh`](https://github.com/superset-sh/superset/blob/main/.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`](https://github.com/superset-sh/superset/blob/main/.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`](https://github.com/superset-sh/superset/blob/main/.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`](https://github.com/superset-sh/superset/blob/main/.superset/config.json). This command launches all services defined in your project's [`docker-compose.yml`](https://github.com/superset-sh/superset/blob/main/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`](https://github.com/superset-sh/superset/blob/main/.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`](https://github.com/superset-sh/superset/blob/main/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`](https://github.com/superset-sh/superset/blob/main/.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.