Setup & Teardown Scripts

Superset can automatically run setup and teardown scripts when creating and deleting workspaces. This is essential for:

Installing dependencies
Copying environment files
Creating database branches
Starting Docker containers
Cleaning up resources

Configuration File

Setup and teardown scripts are configured in .superset/config.json at the root of your repository:

.superset/config.json

{
  "setup": ["./.superset/setup.sh"],
  "teardown": ["./.superset/teardown.sh"]
}

Both setup and teardown accept arrays of commands. You can run multiple scripts or inline commands.

Setup Scripts

Setup scripts run when a new workspace is created. They prepare the workspace environment.

Basic Setup Script

.superset/setup.sh

#!/bin/bash
set -e

# Copy environment variables from root
cp ../.env .env

# Install dependencies
echo "📦 Installing dependencies..."
bun install

# Run database migrations
echo "🗄️  Running migrations..."
bun run db:migrate

echo "✅ Workspace ready!"

Make your script executable: chmod +x .superset/setup.sh

Advanced Setup Script

Here’s a more comprehensive example from the Superset repository:

.superset/setup.sh (Advanced)

#!/usr/bin/env bash
set -uo pipefail

SUPERSET_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

# Source helper libraries
source "$SUPERSET_SCRIPT_DIR/lib/common.sh"
source "$SUPERSET_SCRIPT_DIR/lib/setup/steps.sh"
source "$SUPERSET_SCRIPT_DIR/lib/setup/main.sh"

setup_main "$@"

This script:

Loads environment variables from the root repository
Checks for required dependencies (bun, neonctl, jq, docker, caddy)
Installs npm/bun dependencies
Creates a Neon database branch for the workspace
Starts an Electric SQL Docker container
Allocates unique ports for all services
Writes a workspace-specific .env file
Sets up local MCP server configuration
Seeds authentication tokens and local database

Teardown Scripts

Teardown scripts run when a workspace is deleted. They clean up resources.

Basic Teardown Script

.superset/teardown.sh

#!/bin/bash
set -e

# Stop Docker containers
echo "🛑 Stopping Docker containers..."
docker stop "${WORKSPACE_NAME}-db" 2>/dev/null || true
docker rm "${WORKSPACE_NAME}-db" 2>/dev/null || true

# Delete database branch
if [ -n "$NEON_BRANCH_ID" ]; then
  echo "🗄️  Deleting Neon branch..."
  neonctl branches delete "$NEON_BRANCH_ID" --project-id "$NEON_PROJECT_ID"
fi

echo "✅ Cleanup complete!"

Advanced Teardown Script

From the Superset repository:

.superset/teardown.sh (Advanced)

#!/usr/bin/env bash
set -uo pipefail

SUPERSET_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

source "$SUPERSET_SCRIPT_DIR/lib/common.sh"
source "$SUPERSET_SCRIPT_DIR/lib/teardown/steps.sh"
source "$SUPERSET_SCRIPT_DIR/lib/teardown/main.sh"

teardown_main "$@"

This script:

Stops and removes Electric SQL Docker container
Deletes the Neon database branch
Releases allocated ports
Removes workspace-specific configuration files

Environment Variables

Superset provides these environment variables to setup/teardown scripts:

Variable	Description
`SUPERSET_WORKSPACE_NAME`	Name of the workspace (e.g., `fix-auth-bug`)
`SUPERSET_ROOT_PATH`	Absolute path to the main repository
`SUPERSET_PORT_BASE`	Base port allocated for this workspace (e.g., `3000`)
`PWD`	Current workspace directory path

Using Environment Variables

#!/bin/bash
set -e

echo "Setting up workspace: $SUPERSET_WORKSPACE_NAME"
echo "Root path: $SUPERSET_ROOT_PATH"

# Copy .env from root
cp "$SUPERSET_ROOT_PATH/.env" .env

# Customize for this workspace
echo "WORKSPACE_NAME=$SUPERSET_WORKSPACE_NAME" >> .env
echo "API_PORT=$((SUPERSET_PORT_BASE + 1))" >> .env
echo "WEB_PORT=$((SUPERSET_PORT_BASE + 2))" >> .env

Common Setup Tasks

Installing Dependencies

bun install

Copying Environment Files

# Copy from root repository
cp "$SUPERSET_ROOT_PATH/.env" .env

# Or copy from a template
cp .env.example .env

# Customize for this workspace
echo "DATABASE_URL=postgres://localhost:5432/$SUPERSET_WORKSPACE_NAME" >> .env

Creating Database Branches

# Create a branch for this workspace
BRANCH_NAME="$SUPERSET_WORKSPACE_NAME"
neonctl branches create \
  --project-id "$NEON_PROJECT_ID" \
  --name "$BRANCH_NAME"

# Get connection string
DATABASE_URL=$(neonctl connection-string "$BRANCH_NAME" \
  --project-id "$NEON_PROJECT_ID" \
  --pooled)

echo "DATABASE_URL=$DATABASE_URL" >> .env

Starting Docker Containers

# Start a PostgreSQL container
CONTAINER_NAME="${SUPERSET_WORKSPACE_NAME}-db"
docker run -d \
  --name "$CONTAINER_NAME" \
  -e POSTGRES_PASSWORD=dev \
  -p 5432:5432 \
  postgres:16

# Wait for PostgreSQL to be ready
until docker exec "$CONTAINER_NAME" pg_isready; do
  sleep 1
done

echo "DATABASE_URL=postgres://postgres:dev@localhost:5432/postgres" >> .env

Allocating Unique Ports

# Allocate base port (increases by 20 for each workspace)
BASE_PORT=$((3000 + (WORKSPACE_NUMBER * 20)))

# Calculate service ports
WEB_PORT=$((BASE_PORT + 0))
API_PORT=$((BASE_PORT + 1))
DB_PORT=$((BASE_PORT + 2))

# Write to .env
cat >> .env <<EOF
WEB_PORT=$WEB_PORT
API_PORT=$API_PORT
DB_PORT=$DB_PORT
EOF

Common Teardown Tasks

Stopping Docker Containers

CONTAINER_NAME="${SUPERSET_WORKSPACE_NAME}-db"

# Stop and remove container
docker stop "$CONTAINER_NAME" 2>/dev/null || true
docker rm "$CONTAINER_NAME" 2>/dev/null || true

Deleting Database Branches

if [ -n "$NEON_BRANCH_ID" ]; then
  neonctl branches delete "$NEON_BRANCH_ID" \
    --project-id "$NEON_PROJECT_ID"
fi

Cleaning Up Files

# Remove workspace-specific files
rm -rf .env
rm -rf node_modules
rm -rf .next
rm -rf dist

Testing Scripts

Test your setup script before committing:

Create a Test Workspace

Use ⌘N to create a new workspace. Watch the setup script output in the terminal.

Verify Environment

Check that all dependencies installed correctly:

cat .env
bun --version
docker ps

Test Application

Try running your application:

bun run dev

Test Teardown

Delete the workspace and verify cleanup worked:

Docker containers stopped
Database branches deleted
Files cleaned up

Error Handling

Make your scripts robust with proper error handling:

#!/bin/bash

# Exit on any error
set -e

# Exit on undefined variables
set -u

# Print commands as they execute (debugging)
set -x

# Trap errors and clean up
trap 'echo "❌ Setup failed at line $LINENO"' ERR

# Your setup commands here
echo "📦 Installing dependencies..."
bun install || {
  echo "❌ Failed to install dependencies"
  exit 1
}

echo "✅ Setup complete!"

Best Practices

Make Scripts Idempotent

Scripts should work correctly when run multiple times. Check if resources already exist before creating them.

Use Exit Codes

Return 0 for success, non-zero for failure. Superset will show an error if setup fails.

Provide Clear Output

Use echo to show progress. Helps debug issues when scripts fail.

Clean Up on Failure

Use trap to clean up resources if setup fails halfway through.

Test Thoroughly

Test both setup and teardown scripts before deploying to your team.

Document Dependencies

Add comments listing required CLI tools (bun, docker, neonctl, etc.).

Troubleshooting

Setup script fails silently

If the script fails without showing errors:

Add set -e to exit on any error
Add set -x to print commands as they execute
Check the terminal output in Superset
Test the script manually: ./.superset/setup.sh

Environment variables not available

If SUPERSET_WORKSPACE_NAME or SUPERSET_ROOT_PATH are empty:

Make sure you’re running the script through Superset, not manually
Check that the script is configured in .superset/config.json
Verify the config file is in the repository root

Dependencies not found

If commands like bun or docker aren’t found:

Make sure they’re installed on your system
Check that they’re in your PATH
Try running the command manually first
Add the full path to the binary (e.g., /usr/local/bin/docker)

Teardown leaves resources behind

If Docker containers or database branches aren’t cleaned up:

Add error suppression: command 2>/dev/null || true
Check resource names match what setup created
Manually clean up: docker ps -a, neonctl branches list
Test teardown script manually before deleting workspace

Example: Full Setup Script

Here’s a complete, production-ready setup script:

.superset/setup.sh

#!/usr/bin/env bash
set -euo pipefail

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[0;33m'
NC='\033[0m'

error() { echo -e "${RED}✗${NC} $1" >&2; }
success() { echo -e "${GREEN}✓${NC} $1"; }
info() { echo -e "${YELLOW}→${NC} $1"; }

info "Setting up workspace: $SUPERSET_WORKSPACE_NAME"

# 1. Copy environment file
info "Copying environment file..."
if [ ! -f "$SUPERSET_ROOT_PATH/.env" ]; then
  error "Root .env not found at $SUPERSET_ROOT_PATH/.env"
  exit 1
fi
cp "$SUPERSET_ROOT_PATH/.env" .env
success "Environment file copied"

# 2. Install dependencies
info "Installing dependencies..."
if ! command -v bun &> /dev/null; then
  error "Bun not found. Install from https://bun.sh"
  exit 1
fi
bun install
success "Dependencies installed"

# 3. Set up database
info "Creating database branch..."
if ! command -v neonctl &> /dev/null; then
  error "neonctl not found. Install: npm install -g neonctl"
  exit 1
fi

BRANCH_ID=$(neonctl branches create \
  --project-id "$NEON_PROJECT_ID" \
  --name "$SUPERSET_WORKSPACE_NAME" \
  --output json | jq -r '.branch.id')

DATABASE_URL=$(neonctl connection-string "$BRANCH_ID" \
  --project-id "$NEON_PROJECT_ID" \
  --pooled)

echo "DATABASE_URL=$DATABASE_URL" >> .env
echo "NEON_BRANCH_ID=$BRANCH_ID" >> .env
success "Database branch created"

# 4. Run migrations
info "Running database migrations..."
bun run db:migrate
success "Migrations complete"

# 5. Start Docker containers
info "Starting Docker containers..."
if ! command -v docker &> /dev/null; then
  error "Docker not found. Install from https://docker.com"
  exit 1
fi

CONTAINER_NAME="superset-redis-$SUPERSET_WORKSPACE_NAME"
if docker ps -a --format '{{.Names}}' | grep -q "^${CONTAINER_NAME}$"; then
  info "Container already exists, restarting..."
  docker restart "$CONTAINER_NAME"
else
  docker run -d \
    --name "$CONTAINER_NAME" \
    -p 6379:6379 \
    redis:7-alpine
fi

echo "REDIS_URL=redis://localhost:6379" >> .env
success "Redis container started"

success "Workspace setup complete!"
info "Start development: bun run dev"

Workspace Management

Learn how workspaces are created and deleted

Running Agents

Prepare environments for coding agents

Integrations

Connect to external services and tools

Get Started

Core Concepts

Guides

Resources

Setup & Teardown Scripts

Configuration File

Setup Scripts

Basic Setup Script

Advanced Setup Script

Teardown Scripts

Basic Teardown Script

Advanced Teardown Script

Environment Variables

Using Environment Variables

Common Setup Tasks

Installing Dependencies

Copying Environment Files

Creating Database Branches

Starting Docker Containers

Allocating Unique Ports

Common Teardown Tasks

Stopping Docker Containers

Deleting Database Branches

Cleaning Up Files

Testing Scripts

Error Handling

Best Practices

Make Scripts Idempotent

Use Exit Codes

Provide Clear Output

Clean Up on Failure

Test Thoroughly

Document Dependencies

Troubleshooting

Example: Full Setup Script

Workspace Management

Running Agents

Integrations

Get Started

Core Concepts

Guides

Resources

​Configuration File

​Setup Scripts

​Basic Setup Script

​Advanced Setup Script

​Teardown Scripts

​Basic Teardown Script

​Advanced Teardown Script

​Environment Variables

​Using Environment Variables

​Common Setup Tasks

​Installing Dependencies

​Copying Environment Files

​Creating Database Branches

​Starting Docker Containers

​Allocating Unique Ports

​Common Teardown Tasks

​Stopping Docker Containers

​Deleting Database Branches

​Cleaning Up Files

​Testing Scripts

​Error Handling

​Best Practices

Make Scripts Idempotent

Use Exit Codes

Provide Clear Output

Clean Up on Failure

Test Thoroughly

Document Dependencies

​Troubleshooting

​Example: Full Setup Script

​Related Topics

Workspace Management

Running Agents

Integrations

Configuration File

Setup Scripts

Basic Setup Script

Advanced Setup Script

Teardown Scripts

Basic Teardown Script

Advanced Teardown Script

Environment Variables

Using Environment Variables

Common Setup Tasks

Installing Dependencies

Copying Environment Files

Creating Database Branches

Starting Docker Containers

Allocating Unique Ports

Common Teardown Tasks

Stopping Docker Containers

Deleting Database Branches

Cleaning Up Files

Testing Scripts

Error Handling

Best Practices

Troubleshooting

Example: Full Setup Script

Related Topics