# How to Deploy Apache Superset from Source: Complete Build Guide

> Deploy Apache Superset from source by cloning the superset-sh superset repository. Install Bun and Caddy, configure your env file, and run bun run dev for the full development stack.

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

---

**Deploy Apache Superset from source by cloning the `superset-sh/superset` repository, installing Bun and Caddy, configuring your `.env` file, and running `bun run dev` to start the full development stack.**

This guide covers how to deploy Apache Superset from source using the modern Bun-powered monorepo at `superset-sh/superset`. Unlike traditional Python-based deployments, this version uses a TypeScript stack with Electric SQL synchronization, requiring specific steps for local development and production builds.

## Prerequisites for Deploying Superset from Source

### Install Bun and Caddy

The build system relies on **Bun** for dependency management and **Caddy** as the reverse proxy for Electric SQL streams.

```bash

# Install Bun (macOS/Linux)

curl -fsSL https://bun.sh/install | bash

# Install Caddy (macOS)

brew install caddy

```

For Linux or Windows, follow the official Caddy documentation to install the binary.

### System Requirements

- Git
- macOS, Linux, or Windows with WSL
- Node.js 18+ (for compatibility, though Bun is the primary runtime)

## Step-by-Step Guide to Deploy Apache Superset from Source

### Clone the Repository

Start by cloning the monorepo from GitHub:

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

```

### Configure Environment Variables

Create a local environment file by copying the example configuration found in the repository root:

```bash
cp .env.example .env

```

Edit `.env` to add your database credentials and API keys. For quick testing without full configuration, you can use a minimal stub:

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

```

### Set Up the Reverse Proxy

Copy the example Caddyfile to enable the Electric SQL proxy:

```bash
cp Caddyfile.example Caddyfile

```

This configuration handles the WebSocket streams required for real-time synchronization between the database and frontend components.

### Install Dependencies

Use Bun to install all workspace dependencies across the monorepo:

```bash
bun install

```

This command installs packages for the API (`apps/api`), web UI (`apps/web`), and desktop client (`apps/desktop`).

### Start the Development Servers

Launch the full stack with a single command defined in [`package.json`](https://github.com/superset-sh/superset/blob/main/package.json):

```bash
bun run dev

```

According to the source code, this concurrently starts:
- The **API** on `http://localhost:3000`
- The **Web UI** on `http://localhost:3001` (proxied through Caddy)
- The **Desktop daemon** for terminal integration
- The **Caddy** reverse proxy for Electric SQL streams

### Build the Desktop Client (Optional)

To create a distributable desktop application for production use:

```bash
bun run build
open apps/desktop/release

```

The build process uses the script at [`apps/desktop/create-release.sh`](https://github.com/superset-sh/superset/blob/main/apps/desktop/create-release.sh) to package the binary for distribution.

## Production Deployment Workflow

### Automated CI/CD Pipeline

For production environments, the repository includes a GitHub Actions workflow at [`.github/workflows/deploy-production.yml`](https://github.com/superset-sh/superset/blob/main/.github/workflows/deploy-production.yml) that automates the entire deployment process.

The pipeline executes:
1. **Dependency installation** with `bun install --frozen`
2. **Database migrations** using `bun drizzle-kit migrate` in `packages/db`
3. **API and Web UI deployment** to Vercel
4. **Desktop binary** creation and release

### Database Migrations

Before deploying to production, run migrations via Drizzle to ensure schema consistency:

```bash
cd packages/db
bun drizzle-kit migrate

```

This ensures your database schema matches the current source code version in `packages/db`.

## Summary

- **Clone** the `superset-sh/superset` repository and install **Bun** and **Caddy** as prerequisites.
- **Configure** your environment by copying `.env.example` to `.env` and setting up the `Caddyfile` for Electric SQL proxying.
- **Install** dependencies with `bun install` and start the full development stack using `bun run dev`.
- **Build** the desktop client with `bun run build` when distributing the application.
- **Deploy** to production using the GitHub Actions workflow in [`.github/workflows/deploy-production.yml`](https://github.com/superset-sh/superset/blob/main/.github/workflows/deploy-production.yml), which handles Vercel deployment, database migrations, and desktop binary releases.

## Frequently Asked Questions

### What is the difference between `bun run dev` and `bun run build`?

**`bun run dev`** starts the development servers concurrently, including the API on port 3000, the web UI on port 3001, the desktop daemon, and the Caddy reverse proxy. **`bun run build`** compiles the desktop client into a distributable binary located in `apps/desktop/release` and prepares production assets for the web interface.

### Do I need Caddy for local development?

**Yes**, Caddy is required for local development because it acts as the reverse proxy for Electric SQL streams that enable real-time synchronization between the database and the frontend. The development command `bun run dev` expects a `Caddyfile` to be present in the repository root to configure these WebSocket connections properly.

### How do I deploy Superset to production without using GitHub Actions?

To deploy manually without GitHub Actions, first run database migrations with `bun drizzle-kit migrate` in the `packages/db` directory. Then build the application using `bun run build`, configure your production environment variables in `.env`, and deploy the API and web assets to your preferred hosting platform such as Vercel, Docker, or a VPS. Ensure Caddy or another reverse proxy is configured to handle Electric SQL streams in production.

### What does the [`.superset/setup.sh`](https://github.com/superset-sh/superset/blob/main/.superset/setup.sh) script do?

The [`.superset/setup.sh`](https://github.com/superset-sh/superset/blob/main/.superset/setup.sh) script automates the initial workspace bootstrap by copying `.env.example` to `.env`, installing dependencies with `bun install`, and printing a "Workspace ready!" confirmation message. It is invoked automatically when creating new workspaces and ensures consistent environment setup across development machines according to the repository structure.