How to Deploy Apache Superset from Source: Complete Build Guide

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.

# 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:

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:

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:

echo 'SKIP_ENV_VALIDATION=1' >> .env

Set Up the Reverse Proxy

Copy the example Caddyfile to enable the Electric SQL proxy:

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:

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:

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:

bun run build
open apps/desktop/release

The build process uses the script at 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 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:

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, 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 script do?

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

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