Skip to main content

Setting up Superset in Development Environment

Tutorial to follow along​

We want to set up Superset in development environment to get everything in place to create and test plugins.

Requirements​

  1. Python 3.10 or 3.11
  2. Node.js
    • Node.js: Version 20
    • npm: Version 10

Superset Architecture​

Superset follows a client-server architecture with two main components that need to be run separately in development mode:

1. Backend (Server-side)​

  • Technology: Python with Flask web framework
  • Purpose: Handles data processing, database connections, API endpoints, and business logic
  • Key Features:
    • SQL query execution and optimization
    • Data source connections (databases, APIs)
    • User authentication and authorization
    • Chart and dashboard metadata storage
    • Plugin registration and management
  • Development Server: Runs on http://localhost:8088
  • Hot Reload: Automatically restarts when Python files change

2. Frontend (Client-side)​

  • Technology: React with TypeScript
  • Purpose: User interface, data visualization, and user interactions
  • Key Features:
    • Interactive dashboards and charts
    • Data exploration interface
    • Plugin rendering and management
    • Real-time data updates
  • Development Server: Runs on http://localhost:9000
  • Hot Reload: Automatically refreshes browser when React/TypeScript files change
  • Proxy: Forwards API requests to backend server

Why Separate Development Servers?​

In development mode, both components run independently to enable:

  • Hot reloading for faster development cycles
  • Independent debugging of frontend and backend issues
  • Plugin development with real-time preview
  • API testing with proper CORS configuration

Overall Setup​

1. Clone GitHub Repository​

Clone the repository in a place where we will run it in dev environment with the following commands:

git clone https://github.com/apache/superset.git -b 5.0.0
cd superset

Starting Backend​

1. Create Virtual Environment​

Create a virtual environment using the following commands:

python -m venv venv
source venv/bin/activate
pip install -r requirements/development.txt

2. Create Superset Configuration File for Development​

Create a superset_config.py file in the root directory:

Important: Set the environment variable to point to your config file:

export SUPERSET_CONFIG_PATH=superset_config.py
# superset_config.py
import os

# Enable development features
DEBUG = True
TEMPLATES_AUTO_RELOAD = True

# CORS settings for development
ENABLE_CORS = True
CORS_OPTIONS = {
    'supports_credentials': True,
    'allow_headers': ['*'],
    'resources': {'*': {'origins': '*'}},
}

# Disable CSRF for development
WTF_CSRF_ENABLED = False

# Enable detailed logging
LOG_LEVEL = "DEBUG"

# Frontend configuration
FEATURE_FLAGS = {
    "ENABLE_TEMPLATE_PROCESSING": True,
    "DASHBOARD_NATIVE_FILTERS": True,
    "DASHBOARD_CROSS_FILTERS": True,
    # Enable plugin development features
    "ENABLE_ADVANCED_DATA_TYPES": True,
    "ENABLE_EXPLORE_JSON_CSV": True,
}

# Plugin development settings
SUPERSET_WEBSERVER_TIMEOUT = 300

# Plugin configuration
PLUGIN_CONFIG = {
    "superset_plugin_template": {
        "enabled": True,
    }
}

3. Run Superset Backend​

Run Superset's backend with the following commands:

# Initialize the database
superset db upgrade

# Create an admin user
superset fab create-admin \
    --username admin \
    --firstname Admin \
    --lastname User \
    --email admin@example.com \
    --password admin

# Initialize Superset
superset init

# Start Flask development server
superset run -h 0.0.0.0 -p 8088 --with-threads --reload --debugger

Starting Superset Frontend​

1. Move to Frontend Directory and Install Dependencies​

cd superset-frontend
npm install --force

2. Install Missing Dependencies​

Install missing dependencies to resolve common errors:

# Install packages that are commonly missing and cause build errors
npm install global-box currencyformatter.js @deck.gl/widgets @react-spring/web

3. Fix Webpack Configuration Issues​

Fix issues while running by adding the following to the webpack.config.js file under module -> rules:

// Fix for ESM packages like @luma.gl that don't include file extensions in imports
// This tells webpack not to require fully specified paths (with .js extensions)
{
  test: /\.m?js$/,
  resolve: {
    fullySpecified: false,
  },
},

4. Start Frontend Development Server​

npm run dev-server

The frontend will be available at http://localhost:9000 and will proxy API requests to the backend at http://localhost:8088.

Testing Hot Reload​

Try adding the following CSS at the end of the GlobalStyles.tsx file after other CSS, and you should see a red background:

body {
  background-color: red;
}

🎉 Congratulations!​

You have successfully started Superset in development mode with hot reload!