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

> Learn how to run the Apache Superset development environment quickly. Clone the repo, set up dependencies with Bun, and start the Turbo-monorepo with a single command for efficient development.

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

---

**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.

```bash
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:

```bash
cp .env.example .env

```

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

```bash
echo 'SKIP_ENV_VALIDATION=1' >> .env

```

This configuration is referenced in the root [`package.json`](https://github.com/superset-sh/superset/blob/main/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:

```bash
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:

```bash
bun run dev:caddy

```

This script (defined in [`package.json`](https://github.com/superset-sh/superset/blob/main/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:

```bash
bun run dev

```

This command runs the `dev` pipeline defined in [`turbo.json`](https://github.com/superset-sh/superset/blob/main/turbo.json), which parallelizes development servers for `@superset/api`, `@superset/web`, `@superset/desktop`, and other workspace packages. The root [`package.json`](https://github.com/superset-sh/superset/blob/main/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:

```bash

# 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`](https://github.com/superset-sh/superset/blob/main/.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`](https://github.com/superset-sh/superset/blob/main/.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.