How to Set Up an Apache Superset Development Environment: Complete Turbo-Monorepo Guide

You can run the Apache Superset development environment by cloning the superset-sh/superset repository, copying .env.example to .env, installing dependencies with Bun, and executing bun run dev to start the Turbo-monorepo pipelines and Caddy reverse-proxy.

The superset-sh/superset repository implements Apache Superset as a Turbo-monorepo that bundles multiple applications—including the web interface, API, desktop client, and documentation—into a unified development environment. Unlike the traditional Python-based Apache Superset setup, this architecture uses Bun as the package manager and runtime, orchestrating services through Turborepo pipelines and proxying Electric-SQL streams via Caddy.

Prerequisites

Before setting up the Apache Superset development environment, ensure you have Bun (the JavaScript runtime and package manager) and Caddy (the reverse proxy) installed on your system. The repository is officially supported on macOS and Linux; Windows compatibility is currently untested.

Clone and Configure the Apache Superset Repository

Start by cloning the monorepo and preparing the environment configuration files located in the repository root.

git clone https://github.com/superset-sh/superset.git
cd superset

Environment Configuration

The root directory contains an .env.example file that defines all environment variables required by the various apps. Copy this template to create your local configuration:

cp .env.example .env

For faster initial startup, you can optionally disable environment validation by adding the following line to your .env file:

echo 'SKIP_ENV_VALIDATION=1' >> .env

This configuration is referenced in the root package.json scripts and documented in the monorepo guide at apps/docs/content/docs/using-monorepos.mdx.

Install Dependencies with Bun

Superset uses Bun exclusively for package management and script execution. Install all workspace dependencies with:

bun install

This command installs dependencies for all packages in the monorepo, including @superset/web, @superset/api, @superset/desktop, and shared internal packages.

Start the Development Services

The development environment requires two main components: the Caddy reverse proxy for Electric-SQL streams and the Turbo-monorepo development pipelines.

Launch the Caddy Reverse Proxy

Start the Caddy proxy using the provided Caddyfile configuration:

bun run dev:caddy

This script (defined in package.json) executes dotenv -- caddy run --config Caddyfile, which proxies local Electric-SQL streams required by the real-time synchronization features.

Run the Full Turbo Development Pipeline

With Caddy running (or in a separate terminal), launch all services simultaneously using Turborepo:

bun run dev

This command runs the dev pipeline defined in turbo.json, which parallelizes development servers for @superset/api, @superset/web, @superset/desktop, and other workspace packages. The root package.json defines this as turbo run dev dev:caddy --filter=....

Run Individual Packages

For targeted development on a specific application, use Turborepo's --filter flag to start only the package you need:

# Start only the web application

bun run --filter @superset/web dev &

# Start only the API server

bun run --filter @superset/api dev &

This approach is documented in apps/docs/content/docs/using-monorepos.mdx and conserves system resources when you are not working across the entire stack.

Workspace Lifecycle and Automated Setup

Superset includes an automated workspace system defined in .superset/config.json. When you create a new workspace, the system automatically:

1. Creates a git worktree for the task
2. Copies the .env file to the new workspace
3. Installs dependencies via Bun
4. Executes any custom setup scripts defined in the configuration

This lifecycle management ensures consistent environment setup across different development tasks and branches.

Summary

• Apache Superset (superset-sh/superset) runs as a Turbo-monorepo using Bun and Caddy.
• Copy .env.example to .env and optionally set SKIP_ENV_VALIDATION=1 for faster startup.
• Install dependencies with bun install.
• Start the Caddy proxy with bun run dev:caddy to handle Electric-SQL streams.
• Launch the full stack with bun run dev or target specific packages with bun run --filter @superset/web dev.
• The workspace system in .superset/config.json automates git worktree creation and environment setup.

Frequently Asked Questions

What is the difference between the superset-sh/superset repository and the main Apache Superset project?

The superset-sh/superset repository is a Turbo-monorepo implementation that reimagines Apache Superset as a JavaScript-centric stack using Bun, Turborepo, and Electric-SQL for real-time synchronization. The main Apache Superset project (apache/superset) is a traditional Python Flask application with a React frontend. This monorepo version bundles the web interface, API, desktop client, and documentation into a unified development environment orchestrated by Turborepo pipelines.

Why does the development environment require Caddy?

Caddy serves as a reverse proxy for Electric-SQL streams, which provide real-time database synchronization between the API and clients. The Caddyfile configuration routes these streams correctly during local development. Without Caddy running (via bun run dev:caddy), the real-time synchronization features would fail to connect, though the core web and API applications might still function in isolation.

Can I run individual packages instead of the entire monorepo?

Yes, Turborepo's --filter flag allows you to target specific workspaces. For example, run bun run --filter @superset/web dev to start only the web application, or bun run --filter @superset/api dev for just the backend. This approach conserves system resources and reduces startup time when you are working on a specific component rather than testing full-stack integration.

What should I do if environment validation fails during startup?

If you encounter environment validation errors during your first startup, you can bypass the validation step by setting SKIP_ENV_VALIDATION=1 in your .env file. This is useful for quick local testing, though you should configure all required variables properly for production deployments. The .env.example file in the repository root documents every environment variable used across the web, API, and desktop applications.

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