Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Add mise for automated dev environment setup (#66517)

Nemanja Glumacf72633bd9f92
diff --git a/.gitignore b/.gitignore
index 5b58af9734f..5b50ced8cb2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -111,6 +111,7 @@ dev/serialization_deltas/
/frontend/src/cljs_release
.shadow-cljs
.clerk
+mise.local.toml
# lsp: ignore all but the config file
.lsp/*
diff --git a/bb.edn b/bb.edn
index 33416d7d7be..416f3ce854d 100644
--- a/bb.edn
+++ b/bb.edn
@@ -1,4 +1,4 @@
-{:min-bb-version "1.12.208"
+{:min-bb-version "1.12.212"
;; we put path as bin, and everything is in the ./mage subdirectory,
;; so the namespaces are mage.cli, mage.format, etc.
:paths ["mage/src" "mage/test" "bin/lint-migrations-file/src"]
diff --git a/bin/dev-bootstrap b/bin/dev-deps
similarity index 72%
rename from bin/dev-bootstrap
rename to bin/dev-deps
index 6b7110b6067..ea73c83c415 100755
--- a/bin/dev-bootstrap
+++ b/bin/dev-deps
@@ -8,13 +8,13 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
source "$SCRIPT_DIR/utils/all.sh"
# Lock directory to prevent concurrent runs
-LOCK_DIR="$PROJECT_ROOT/logs/dev-bootstrap.lock"
+LOCK_DIR="$PROJECT_ROOT/logs/dev-deps.lock"
acquire_lock() {
mkdir -p "$(dirname "$LOCK_DIR")"
# Use mkdir for atomic lock acquisition
if ! mkdir "$LOCK_DIR" 2>/dev/null; then
- print_error "Bootstrap is already running"
+ print_error "dev-deps is already running"
echo " If this is a mistake, run: rm -rf $LOCK_DIR"
exit 1
fi
@@ -31,19 +31,19 @@ check_required_tools() {
# If any of these tools are an incorrect version, the build
# step will fail later on, so we just check for their presence here.
- if ! command -v node &> /dev/null; then
+ if ! has_tool node; then
missing+=("node")
fi
- if ! command -v yarn &> /dev/null; then
+ if ! has_tool yarn; then
missing+=("yarn")
fi
- if ! command -v java &> /dev/null; then
+ if ! has_tool java; then
missing+=("java")
fi
- if ! command -v clojure &> /dev/null; then
+ if ! has_tool clojure; then
missing+=("clojure")
fi
@@ -52,7 +52,7 @@ check_required_tools() {
echo ""
echo "Run ./bin/dev-requirements to check your development environment."
echo ""
- echo "If you'd like an automated setup, run ./bin/dev-install which uses mise (coming soon)."
+ echo "If you'd like an automated setup, run ./bin/dev-install (uses mise)."
exit 1
fi
}
@@ -93,15 +93,6 @@ build_jar() {
main() {
acquire_lock
- print_header "Metabase Development Bootstrap"
-
- echo "This script will:"
- echo " 1. Verify required tools are installed"
- echo " 2. Install frontend dependencies (yarn)"
- echo " 3. Download backend dependencies (Clojure)"
- echo " 4. Build the Metabase JAR"
- echo ""
-
print_step "Checking required tools"
check_required_tools
print_success "All required tools found"
@@ -130,20 +121,9 @@ main() {
fi
fi
- print_header "Bootstrap Complete!"
-
- echo "Your development environment is ready."
- echo ""
- echo "To start the backend (from source):"
- echo " clj -M:dev:drivers:drivers-dev:ee:ee-dev:dev-start --hot"
- echo ""
- echo "To start the backend (from JAR):"
- echo " java --add-opens java.base/java.nio=ALL-UNNAMED -jar target/uberjar/metabase.jar"
- echo ""
- echo "To start the frontend:"
- echo " yarn build-hot"
echo ""
- echo "For more information, see docs/developers-guide/devenv.md"
+ print_success "Dependencies downloaded"
+ echo " For more information, see docs/developers-guide/devenv.md"
echo ""
}
diff --git a/bin/dev-install b/bin/dev-install
new file mode 100755
index 00000000000..04cee1410d4
--- /dev/null
+++ b/bin/dev-install
@@ -0,0 +1,510 @@
+#!/usr/bin/env bash
+# Automated Metabase development environment setup using mise.
+# This script installs mise, configures shell integration, and sets up all required tools.
+#
+# Usage: ./bin/dev-install
+#
+# Safe to run multiple times (idempotent).
+
+set -euo pipefail
+
+# Check if mise was already active in the parent shell before we do anything
+MISE_WAS_ACTIVE="${MISE_SHELL:-}"
+
+# Load shared utilities
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+source "$SCRIPT_DIR/utils/all.sh"
+
+# Lock directory to prevent concurrent runs
+LOCK_DIR="$PROJECT_ROOT/logs/dev-install.lock"
+
+acquire_lock() {
+ mkdir -p "$(dirname "$LOCK_DIR")"
+ # Use mkdir for atomic lock acquisition
+ if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+ print_error "dev-install is already running"
+ echo " If this is a mistake, run: rm -rf $LOCK_DIR"
+ exit 1
+ fi
+ # Set trap only after successfully acquiring lock
+ trap release_lock EXIT
+}
+
+release_lock() {
+ rm -rf "$LOCK_DIR"
+}
+
+# =============================================================================
+# Environment Detection
+# =============================================================================
+
+detect_os() {
+ case "$(uname -s)" in
+ Darwin) echo "macos" ;;
+ Linux) echo "linux" ;;
+ *) echo "unknown" ;;
+ esac
+}
+
+detect_arch() {
+ case "$(uname -m)" in
+ x86_64) echo "x86_64" ;;
+ aarch64) echo "arm64" ;;
+ arm64) echo "arm64" ;;
+ *) echo "unknown" ;;
+ esac
+}
+
+detect_shell() {
+ # Use $SHELL (login shell) since that's what rc files we want to configure.
+ # The user may be running this script from a different shell, but their
+ # login shell is what new terminal windows will use.
+ local shell_name
+ shell_name=$(basename "$SHELL")
+ case "$shell_name" in
+ bash|zsh|fish) echo "$shell_name" ;;
+ *) echo "unknown" ;;
+ esac
+}
+
+get_shell_rc_file() {
+ local shell_name=$1
+ case "$shell_name" in
+ bash)
+ # macOS Terminal.app opens login shells, which source .bash_profile (not .bashrc).
+ # Linux terminals typically open non-login shells, which source .bashrc.
+ # We need to pick the right file based on OS and what already exists.
+ if [ "$(uname -s)" = "Darwin" ]; then
+ # macOS: prefer .bash_profile for login shells
+ if [ -f "$HOME/.bash_profile" ]; then
+ echo "$HOME/.bash_profile"
+ elif [ -f "$HOME/.bashrc" ]; then
+ # User has .bashrc but no .bash_profile - they likely source it manually
+ echo "$HOME/.bashrc"
+ else
+ # Fresh setup: use .bash_profile since that's what macOS sources
+ echo "$HOME/.bash_profile"
+ fi
+ else
+ # Linux: prefer .bashrc for interactive non-login shells
+ if [ -f "$HOME/.bashrc" ]; then
+ echo "$HOME/.bashrc"
+ elif [ -f "$HOME/.bash_profile" ]; then
+ echo "$HOME/.bash_profile"
+ else
+ echo "$HOME/.bashrc"
+ fi
+ fi
+ ;;
+ zsh) echo "$HOME/.zshrc" ;;
+ fish) echo "${XDG_CONFIG_HOME:-$HOME/.config}/fish/config.fish" ;;
+ *) echo "" ;;
+ esac
+}
+
+get_mise_activation_line() {
+ local shell_name=$1
+ case "$shell_name" in
+ bash) echo 'eval "$(mise activate bash)"' ;;
+ zsh) echo 'eval "$(mise activate zsh)"' ;;
+ fish) echo 'mise activate fish | source' ;;
+ *) echo "" ;;
+ esac
+}
+
+# =============================================================================
+# Installation Functions
+# =============================================================================
+
+install_mise_official() {
+ print_info "Installing mise via official installer"
+
+ if ! has_tool curl; then
+ print_error "curl is required but not installed"
+ exit 1
+ fi
+
+ # Use shell-specific installer that also configures activation
+ local shell_name=$(detect_shell)
+ local installer_url="https://mise.run"
+
+ case "$shell_name" in
+ bash|zsh|fish)
+ installer_url="https://mise.run/$shell_name"
+ ;;
+ esac
+
+ if curl -fsSL "$installer_url" | sh; then
+ print_success "mise installed via official installer"
+
+ # Add to PATH for this session
+ export PATH="$HOME/.local/bin:$PATH"
+ return 0
+ else
+ print_error "Failed to install mise"
+ exit 1
+ fi
+}
+
+update_mise() {
+ # mise self-update is unavailable when installed via package manager
+ # It will exit with an error in that case, which we handle gracefully
+ if mise self-update -y 2>/dev/null; then
+ print_success "mise is up to date ($(mise --version))"
+ else
+ print_info "mise update skipped (managed externally or already current)"
+ fi
+}
+
+is_homebrew_mise() {
+ local mise_path
+ mise_path=$(command -v mise 2>/dev/null) || return 1
+ # Check for Homebrew paths on both Apple Silicon (/opt/homebrew) and Intel Macs (/usr/local)
+ [[ "$mise_path" == *homebrew* || "$mise_path" == *Cellar* || "$mise_path" == /opt/homebrew/* || "$mise_path" == /usr/local/bin/mise ]]
+}
+
+migrate_from_homebrew() {
+ print_warning "mise is currently installed via Homebrew"
+ echo ""
+ echo " We recommend using the official mise installer instead of Homebrew."
+ echo " This provides faster updates and better self-update support."
+ echo ""
+ echo " This will:"
+ echo " 1. Uninstall mise from Homebrew (your tools/configs are preserved)"
+ echo " 2. Install mise to ~/.local/bin via the official installer"
+ echo ""
+
+ if ask_yes_no "Switch to official mise install?" "y"; then
+ print_info "Uninstalling Homebrew mise..."
+ if brew uninstall mise 2>/dev/null; then
+ print_success "Homebrew mise uninstalled"
+ else
+ print_warning "Could not uninstall via Homebrew (may already be removed)"
+ fi
+
+ # Clean up cached files and orphaned dependencies
+ brew cleanup mise 2>/dev/null || true
+ brew autoremove 2>/dev/null || true
+
+ # Install official version
+ install_mise_official
+
+ # Check for stale Homebrew paths in shell config
+ local shell_name=$(detect_shell)
+ local rc_file=$(get_shell_rc_file "$shell_name")
+ if [ -n "$rc_file" ] && [ -f "$rc_file" ]; then
+ if grep -q "homebrew.*mise" "$rc_file" 2>/dev/null; then
+ echo ""
+ print_warning "Found Homebrew mise references in $rc_file"
+ echo " You may want to remove any lines containing '/opt/homebrew' and 'mise'"
+ echo " The official mise installer uses ~/.local/bin/mise instead."
+ fi
+ fi
+
+ return 0
+ else
+ print_info "Keeping Homebrew mise installation"
+ update_mise
+ return 0
+ fi
+}
+
+install_mise() {
+ if has_tool mise; then
+ local version=$(mise --version 2>/dev/null || echo "unknown")
+
+ # Check if installed via Homebrew and offer migration
+ if is_homebrew_mise && has_tool brew; then
+ migrate_from_homebrew
+ return 0
+ fi
+
+ print_success "mise is already installed ($version)"
+ update_mise
+ return 0
+ fi
+
+ local os=$(detect_os)
+
+ case "$os" in
+ macos)
+ install_mise_official
+ ;;
+ linux)
+ install_mise_official
+ ;;
+ *)
+ print_error "Unsupported operating system: $os"
+ exit 1
+ ;;
+ esac
+}
+
+# =============================================================================
+# Shell Integration
+# =============================================================================
+
+# Check shell integration status
+# Returns via global SHELL_INTEGRATION_STATUS:
+# "active" - mise activation is present and uncommented
+# "commented" - mise activation exists but is commented out
+# "none" - no mise activation found
+check_shell_integration() {
+ local rc_file=$1
+ SHELL_INTEGRATION_STATUS="none"
+
+ if [ ! -f "$rc_file" ]; then
+ return 1
+ fi
+
+ # Check for uncommented mise activation (line that doesn't start with # after optional whitespace)
+ if grep -qE '^[^#]*(eval.*mise activate|mise activate)' "$rc_file" 2>/dev/null; then
+ SHELL_INTEGRATION_STATUS="active"
+ return 0
+ fi
+
+ # Check for commented mise activation
+ if grep -qE '^[[:space:]]*#.*(eval.*mise activate|mise activate)' "$rc_file" 2>/dev/null; then
+ SHELL_INTEGRATION_STATUS="commented"
+ return 0
+ fi
+
+ return 1
+}
+
+setup_shell_integration() {
+ local shell_name=$(detect_shell)
+
+ if [ "$shell_name" = "unknown" ]; then
+ print_warning "Unknown shell: $SHELL"
+ echo " Please manually add mise activation to your shell config."
+ echo " See: https://mise.jdx.dev/getting-started.html#activate-mise"
+ return 0
+ fi
+
+ local rc_file=$(get_shell_rc_file "$shell_name")
+ local activation_line=$(get_mise_activation_line "$shell_name")
+
+ if [ -z "$rc_file" ]; then
+ print_warning "Could not determine shell config file"
+ return 0
+ fi
+
+ check_shell_integration "$rc_file"
+
+ if [ "$SHELL_INTEGRATION_STATUS" = "active" ]; then
+ print_success "Shell integration already configured in $rc_file"
+ return 0
+ fi
+
+ if [ "$SHELL_INTEGRATION_STATUS" = "commented" ]; then
+ print_warning "Found commented-out mise activation in $rc_file"
+ echo " It looks like mise activation was previously disabled."
+ echo ""
+ if ask_yes_no "Add a new mise activation line?" "n"; then
+ echo "" >> "$rc_file"
+ echo "# mise - dev tool version manager" >> "$rc_file"
+ echo "$activation_line" >> "$rc_file"
+ print_success "Added mise activation to $rc_file"
+ echo " You may want to remove the old commented line manually."
+ else
+ print_info "Keeping current configuration"
+ echo " To enable mise, uncomment the existing line in $rc_file"
+ fi
+ return 0
+ fi
+
+ # No mise activation found - offer to add it
+ print_step "Shell integration"
+ echo " mise needs to be activated in your shell to work automatically."
+ echo " This will add the following line to $rc_file:"
+ echo ""
+ echo " $activation_line"
+ echo ""
+
+ if ask_yes_no "Add mise to your shell config?" "y"; then
+ # Create rc file if it doesn't exist
+ mkdir -p "$(dirname "$rc_file")"
+ touch "$rc_file"
+
+ # Add activation line
+ echo "" >> "$rc_file"
+ echo "# mise - dev tool version manager" >> "$rc_file"
+ echo "$activation_line" >> "$rc_file"
+
+ print_success "Added mise activation to $rc_file"
+ echo " mise is available in this script and will auto-activate in new shells"
+ else
+ print_warning "Skipped shell integration"
+ echo " You'll need to manually activate mise in each session:"
+ echo " $activation_line"
+ fi
+}
+
+# =============================================================================
+# Tool Installation
+# =============================================================================
+
+install_tools() {
+ cd "$PROJECT_ROOT"
+
+ # Verify mise.toml exists
+ if [ ! -f "mise.toml" ] && [ ! -f ".mise.toml" ]; then
+ print_error "No mise.toml found in $PROJECT_ROOT"
+ return 1
+ fi
+
+ # Trust the mise.toml file
+ # --all flag may not exist in older versions, fall back to basic trust
+ if ! mise trust --all 2>/dev/null; then
+ if ! mise trust 2>/dev/null; then
+ print_warning "Could not trust mise.toml (may need manual: mise trust)"
+ fi
+ fi
+
+ # Install all tools
+ if mise install; then
+ print_success "All tools installed successfully"
+ else
+ print_error "Failed to install some tools"
+ echo " Try running 'mise install' manually to see detailed errors"
+ return 1
+ fi
+}
+
+# =============================================================================
+# Main
+# =============================================================================
+
+main() {
+ acquire_lock
+
+ print_header "Metabase Development Environment Setup"
+
+ echo "This script will:"
+ echo " 1. Check prerequisites"
+ echo -e "${DIM} - Checks your OS, shell, curl installed, etc. ${NC}"
+ echo " 2. Install/update mise"
+ echo -e "${DIM} - Installs if needed or checks for updates${NC}"
+ echo " 3. Configure shell integration (with your permission)"
+ echo -e "${DIM} - Puts everything you need on your path when you cd into the project${NC}"
+ echo " 4. Install all required development tools"
+ echo -e "${DIM} - Installs Node.js, Yarn, Clojure, etc.${NC}"
+ echo " 5. Run dev-deps to download project dependencies"
+ echo -e "${DIM} - Downloads and caches JavaScript and Clojure libraries${NC}"
+ echo -e "${DIM} and optionally builds a jar${NC}"
+ echo ""
+
+ ask_yes_no "Are you ready?" "y" || exit 1
+
+ # Check prerequisites
+ print_step "1. Check prerequisites"
+
+ local os=$(detect_os)
+ local arch=$(detect_arch)
+ local shell_name=$(detect_shell)
+
+ if [ "$os" = "unknown" ]; then
+ print_error "Unsupported operating system"
+ exit 1
+ fi
+
+ print_success "OS: $os ($arch)"
+ print_success "Shell: $shell_name"
+
+ if [ "$(id -u)" = "0" ]; then
+ print_warning "Running as root is not recommended"
+ if ! ask_yes_no "Continue anyway?" "n"; then
+ exit 1
+ fi
+ fi
+
+ if ! has_tool curl; then
+ print_error "curl is required but not installed"
+ exit 1
+ fi
+ print_success "curl is available"
+
+ print_step "2. Install/update mise"
+ # Install mise
+ install_mise
+
+ # Verify mise is now available
+ if ! has_tool mise; then
+ # Try adding common mise locations to PATH
+ export PATH="$HOME/.local/bin:$HOME/.mise/bin:$PATH"
+
+ if ! has_tool mise; then
+ print_error "mise installation succeeded but 'mise' command not found"
+ echo " Try restarting your shell and running this script again"
+ exit 1
+ fi
+ fi
+
+ # Setup shell integration (only needed if mise was already installed,
+ # since the official installer handles this for new installs)
+ print_step "3. Configure shell integration"
+ setup_shell_integration
+
+ print_step "4. Install development tools"
+ install_tools
+
+ # Activate mise for this script session so installed tools are available
+ eval "$(mise activate bash)"
+
+ # Run dev-deps
+ print_step "5. Run dev-deps"
+ echo ""
+ if ask_yes_no "Run dev-deps to complete setup by downloading libraries?" "y"; then
+ echo ""
+ print_step "Running bin/dev-deps"
+ echo ""
+ "$SCRIPT_DIR/dev-deps"
+ else
+ print_warning "Skipped dev-deps"
+ echo " Run './bin/dev-deps' when you're ready to complete setup"
+ fi
+
+ print_header "Setup Complete!"
+
+ echo "Your development environment is ready."
+ echo ""
+
+ # Check if mise was already active in the parent shell
+ if [ -n "$MISE_WAS_ACTIVE" ]; then
+ # mise was already active in parent shell
+ echo -e "${BOLD}${GREEN}mise is already active in this shell - you're ready to go!${NC}"
+ echo ""
+ else
+ # Provide next steps for activating mise
+ local shell_name=$(detect_shell)
+ echo -e "${BOLD}${GREEN}Next step: Open a new terminal window to get started.${NC}"
+ echo ""
+ echo -e "${DIM}(Or to continue in this terminal, run:"
+ if [ "$shell_name" = "zsh" ]; then
+ echo " eval \"\$(mise activate zsh)\""
+ elif [ "$shell_name" = "bash" ]; then
+ echo " eval \"\$(mise activate bash)\""
+ elif [ "$shell_name" = "fish" ]; then
+ echo " mise activate fish | source"
+ else
+ echo " eval \"\$(mise activate)\""
+ fi
+ echo -e ")${NC}"
+ echo ""
+ fi
+ echo -e "${BOLD}Then start developing:${NC}"
+ echo ""
+ echo "Backend in one terminal, either:"
+ echo " - from source, with hot reloading:"
+ echo " clojure -M:dev:drivers:drivers-dev:ee:ee-dev:dev-start --hot"
+ echo " - from a pre-built JAR:"
+ echo " java --add-opens java.base/java.nio=ALL-UNNAMED -jar target/uberjar/metabase.jar"
+ echo ""
+ echo "Frontend in another terminal:"
+ echo " yarn build-hot"
+ echo ""
+}
+
+main "$@"
diff --git a/bin/dev-requirements b/bin/dev-requirements
index ccfa0a11555..6febfae7a71 100755
--- a/bin/dev-requirements
+++ b/bin/dev-requirements
@@ -19,7 +19,7 @@ print_optional_tool() {
local cmd=$1
local name=$2
local url=$3
- if command -v "$cmd" &> /dev/null; then
+ if has_tool "$cmd"; then
echo -e " ${GREEN}✓${NC} $name"
else
echo -e " ${RED}✗${NC} $name"
@@ -27,166 +27,6 @@ print_optional_tool() {
echo -e " ${DIM}$url${NC}"
}
-# Detection functions
-detect_version_managers() {
- local managers=()
-
- # nvm - Node Version Manager
- if [ -d "$HOME/.nvm" ] || [ -n "${NVM_DIR:-}" ] || command -v nvm &> /dev/null; then
- managers+=("nvm")
- fi
-
- # fnm - Fast Node Manager
- if command -v fnm &> /dev/null || [ -d "$HOME/.fnm" ]; then
- managers+=("fnm")
- fi
-
- # n - Node version management (no subcommands)
- if command -v n &> /dev/null || [ -d "/usr/local/n" ]; then
- managers+=("n")
- fi
-
- # volta - JavaScript Tool Manager
- if command -v volta &> /dev/null || [ -d "$HOME/.volta" ]; then
- managers+=("volta")
- fi
-
- # asdf - Extendable version manager (multi-language)
- if [ -d "$HOME/.asdf" ] || command -v asdf &> /dev/null; then
- managers+=("asdf")
- fi
-
- # mise - Dev tools version manager (formerly rtx)
- if command -v mise &> /dev/null || [ -d "$HOME/.local/share/mise" ] || [ -d "$HOME/.mise" ]; then
- managers+=("mise")
- fi
-
- # jenv - Java version manager
- if [ -d "$HOME/.jenv" ] || command -v jenv &> /dev/null; then
- managers+=("jenv")
- fi
-
- # SDKMAN! - Software Development Kit Manager (Java, Gradle, Maven, etc.)
- if [ -d "$HOME/.sdkman" ] || [ -n "${SDKMAN_DIR:-}" ]; then
- managers+=("sdkman")
- fi
-
- echo "${managers[@]}"
-}
-
-get_node_version() {
- if command -v node &> /dev/null; then
- node --version
- else
- echo ""
- fi
-}
-
-get_yarn_version() {
- if command -v yarn &> /dev/null; then
- yarn --version
- else
- echo ""
- fi
-}
-
-get_java_version() {
- if command -v java &> /dev/null; then
- java -version 2>&1 | head -n 1 | awk -F '"' '{print $2}'
- else
- echo ""
- fi
-}
-
-get_java_distribution() {
- if command -v java &> /dev/null; then
- local full_version=$(java -version 2>&1)
-
- # Check for various distributions
- if echo "$full_version" | grep -qi "Temurin"; then
- echo "Eclipse Temurin"
- elif echo "$full_version" | grep -qi "Adoptium"; then
- echo "Eclipse Adoptium"
- elif echo "$full_version" | grep -qi "Oracle"; then
- echo "Oracle"
- elif echo "$full_version" | grep -qi "OpenJDK"; then
- echo "OpenJDK"
- elif echo "$full_version" | grep -qi "Amazon Corretto"; then
- echo "Amazon Corretto"
- elif echo "$full_version" | grep -qi "Azul Zulu"; then
- echo "Azul Zulu"
- elif echo "$full_version" | grep -qi "GraalVM"; then
- echo "GraalVM"
- else
- echo "Unknown"
- fi
- else
- echo ""
- fi
-}
-
-check_java_requirements() {
- local version=$1
- local distribution=$2
- local major_version=""
-
- if [ -n "$version" ]; then
- # Extract major version (handles both "21.0.1" and "1.8.0" formats)
- if [[ $version =~ ^1\. ]]; then
- major_version=$(echo "$version" | cut -d. -f2)
- else
- major_version=$(echo "$version" | cut -d. -f1)
- fi
-
- # Check version and distribution
- if [ "$major_version" = "21" ] && [[ "$distribution" =~ "Temurin" ]]; then
- echo "correct"
- elif [ "$major_version" = "21" ]; then
- echo "wrong_distribution"
- else
- echo "wrong_version"
- fi
- else
- echo "not_installed"
- fi
-}
-
-get_clojure_version() {
- if command -v clojure &> /dev/null; then
- clojure --version 2>&1 | head -n 1
- else
- echo ""
- fi
-}
-
-get_required_clojure_version() {
- if [ -f "deps.edn" ]; then
- # Extract org.clojure/clojure version from deps.edn
- grep "org.clojure/clojure" deps.edn | grep ":mvn/version" | sed -E 's/.*"([0-9.]+)".*/\1/' | head -n 1
- else
- echo ""
- fi
-}
-
-get_babashka_version() {
- if command -v bb &> /dev/null; then
- bb --version
- else
- echo ""
- fi
-}
-
-check_yarn_classic() {
- local version=$1
- if [ -n "$version" ]; then
- local major_version=$(echo "$version" | cut -d. -f1)
- if [ "$major_version" = "1" ]; then
- return 0
- fi
- fi
- return 1
-}
-
main() {
print_header "Metabase Development Environment Detection"
@@ -223,7 +63,8 @@ main() {
print_section "Installed Development Tools"
- requirements_met=true
+ # Track issues for final summary
+ issues=()
# Node.js
node_version=$(get_node_version)
@@ -233,11 +74,11 @@ main() {
print_found "Node.js $node_version (meets requirement: >= 22)"
else
print_warning "Node.js $node_version (required: >= 22)"
- requirements_met=false
+ issues+=("Node.js: version $node_version is too old (need >= 22)")
fi
else
print_not_found "Node.js (required: >= 22)"
- requirements_met=false
+ issues+=("Node.js: not installed (need >= 22)")
fi
# Yarn
@@ -247,11 +88,11 @@ main() {
print_found "Yarn $yarn_version (Yarn Classic - correct!)"
else
print_warning "Yarn $yarn_version (required: Yarn Classic 1.x)"
- requirements_met=false
+ issues+=("Yarn: version $yarn_version is not Yarn Classic 1.x")
fi
else
print_not_found "Yarn (required: Yarn Classic 1.x)"
- requirements_met=false
+ issues+=("Yarn: not installed (need Yarn Classic 1.x)")
fi
# Java
@@ -266,16 +107,16 @@ main() {
"wrong_distribution")
print_warning "Java $java_version ($java_distribution)"
echo " Required: Java 21 (Eclipse Temurin)"
- requirements_met=false
+ issues+=("Java: wrong distribution '$java_distribution' (need Eclipse Temurin)")
;;
"wrong_version")
print_warning "Java $java_version ($java_distribution)"
echo " Required: Java 21 (Eclipse Temurin)"
- requirements_met=false
+ issues+=("Java: version $java_version is incorrect (need Java 21)")
;;
"not_installed")
print_not_found "Java (required: Java 21 Eclipse Temurin)"
- requirements_met=false
+ issues+=("Java: not installed (need Java 21 Eclipse Temurin)")
;;
esac
@@ -292,10 +133,11 @@ main() {
else
if [ -n "$required_clojure_version" ]; then
print_not_found "Clojure CLI (required for Clojure $required_clojure_version)"
+ issues+=("Clojure CLI: not installed (need for Clojure $required_clojure_version)")
else
print_not_found "Clojure CLI"
+ issues+=("Clojure CLI: not installed")
fi
- requirements_met=false
fi
# Babashka
@@ -304,18 +146,7 @@ main() {
print_found "Babashka $bb_version"
else
print_not_found "Babashka (required for mage task automation)"
- requirements_met=false
- fi
-
- # Show warning if requirements are not met
- if [ "$requirements_met" = false ]; then
- echo ""
- echo -e " ${BOLD}${RED}⚠ REQUIREMENTS NOT MET ⚠${NC}"
- echo ""
- echo -e " ${BOLD}Your current setup does not meet Metabase's requirements.${NC}"
- echo " The project will not work until the issues above are resolved."
- echo ""
- echo " Please install or update the missing/incorrect tools listed above."
+ issues+=("Babashka: not installed (needed for mage)")
fi
print_section "Metabase Project Requirements"
@@ -345,6 +176,7 @@ main() {
print_section "Recommended Setup"
+ echo ""
echo -e " ${BOLD}${GREEN}We recommend using 'mise'${NC} for version management because:"
echo " - Manages Node.js, Java, and other tools in one place"
echo " - Automatically switches versions per-project"
@@ -352,8 +184,47 @@ main() {
echo ""
echo " Learn more: https://mise.jdx.dev/getting-started.html"
- # Footer
- print_header "Detection Complete"
+ if has_tool mise; then
+ echo ""
+ echo -e " ${BOLD}${GREEN}Good news!${NC} You have mise installed."
+ echo " If you haven't already, consider configuring Metabase to use mise via 'bin/dev-install'."
+ echo ""
+
+ echo "Running 'mise doctor' to check your mise setup..."
+ if mise doctor &>/dev/null; then
+ print_success "${BOLD}mise doctor${NC} gives you a clean bill of health 🩺"
+ else
+ print_error "mise doctor found some issues:"
+ echo ""
+ mise doctor
+ fi
+ else
+ echo ""
+ echo -e " ${BOLD}Next Steps:${NC}"
+ echo " - Run './bin/dev-install' to set up your development environment automatically."
+ fi
+
+ # Final Verdict
+ print_header "Verdict"
+
+ if [ ${#issues[@]} -eq 0 ]; then
+ echo ""
+ echo -e " ${BOLD}${GREEN}✓ You're good to go!${NC} All requirements met."
+ echo " Your dev environment is ready to build Metabase. 🚀"
+ echo ""
+ echo ""
+ else
+ echo ""
+ echo -e " ${BOLD}${RED}✗ Not quite there yet.${NC} Found ${#issues[@]} issue(s):"
+ echo ""
+ for issue in "${issues[@]}"; do
+ echo -e " ${RED}•${NC} $issue"
+ done
+ echo ""
+ echo -e " ${BOLD}Tip:${NC} Run ${GREEN}${BOLD}./bin/dev-install${NC} to fix these automatically."
+ echo ""
+ echo ""
+ fi
echo "For detailed development environment setup, see:"
echo " docs/developers-guide/devenv.md"
diff --git a/bin/utils/all.sh b/bin/utils/all.sh
index 070329c9f34..0b1d4ff0e01 100644
--- a/bin/utils/all.sh
+++ b/bin/utils/all.sh
@@ -18,5 +18,6 @@ source "$_DEVUTILS_DIR/colors.sh"
source "$_DEVUTILS_DIR/logging.sh"
source "$_DEVUTILS_DIR/prompts.sh"
source "$_DEVUTILS_DIR/files.sh"
+source "$_DEVUTILS_DIR/tools.sh"
unset _DEVUTILS_DIR
diff --git a/bin/utils/tools.sh b/bin/utils/tools.sh
new file mode 100644
index 00000000000..228a2dece3b
--- /dev/null
+++ b/bin/utils/tools.sh
@@ -0,0 +1,208 @@
+# bin/utils/tools.sh - Tool detection and version checking utilities
+# Source this file to get tool-related helper functions.
+#
+# Usage:
+# source "$(dirname "${BASH_SOURCE[0]}")/utils/tools.sh"
+# if has_tool java; then
+# version=$(get_java_version)
+# fi
+#
+# Provides: has_tool, get_*_version, check_*_requirements
+
+# Guard against multiple inclusion
+[[ -n "${_DEVUTILS_TOOLS_LOADED:-}" ]] && return 0
+_DEVUTILS_TOOLS_LOADED=1
+
+# =============================================================================
+# Generic Tool Detection
+# =============================================================================
+
+# Check if a command/tool is available
+# Usage: has_tool java
+# Returns: 0 if found, 1 if not found
+has_tool() {
+ command -v "$1" &> /dev/null
+}
+
+# =============================================================================
+# Node.js
+# =============================================================================
+
+get_node_version() {
+ if has_tool node; then
+ node --version
+ else
+ echo ""
+ fi
+}
+
+# =============================================================================
+# Yarn
+# =============================================================================
+
+get_yarn_version() {
+ if has_tool yarn; then
+ yarn --version
+ else
+ echo ""
+ fi
+}
+
+check_yarn_classic() {
+ local version=$1
+ if [ -n "$version" ]; then
+ local major_version=$(echo "$version" | cut -d. -f1)
+ if [ "$major_version" = "1" ]; then
+ return 0
+ fi
+ fi
+ return 1
+}
+
+# =============================================================================
+# Java
+# =============================================================================
+
+get_java_version() {
+ if has_tool java; then
+ java -version 2>&1 | head -n 1 | awk -F '"' '{print $2}'
+ else
+ echo ""
+ fi
+}
+
+get_java_distribution() {
+ if has_tool java; then
+ local full_version=$(java -version 2>&1)
+
+ # Check for various distributions
+ if echo "$full_version" | grep -qi "Temurin"; then
+ echo "Eclipse Temurin"
+ elif echo "$full_version" | grep -qi "Adoptium"; then
+ echo "Eclipse Adoptium"
+ elif echo "$full_version" | grep -qi "Oracle"; then
+ echo "Oracle"
+ elif echo "$full_version" | grep -qi "OpenJDK"; then
+ echo "OpenJDK"
+ elif echo "$full_version" | grep -qi "Amazon Corretto"; then
+ echo "Amazon Corretto"
+ elif echo "$full_version" | grep -qi "Azul Zulu"; then
+ echo "Azul Zulu"
+ elif echo "$full_version" | grep -qi "GraalVM"; then
+ echo "GraalVM"
+ else
+ echo "Unknown"
+ fi
+ else
+ echo ""
+ fi
+}
+
+check_java_requirements() {
+ local version=$1
+ local distribution=$2
+ local major_version=""
+
+ if [ -n "$version" ]; then
+ # Extract major version (handles both "21.0.1" and "1.8.0" formats)
+ if [[ $version =~ ^1\. ]]; then
+ major_version=$(echo "$version" | cut -d. -f2)
+ else
+ major_version=$(echo "$version" | cut -d. -f1)
+ fi
+
+ # Check version and distribution
+ if [ "$major_version" = "21" ] && [[ "$distribution" =~ "Temurin" ]]; then
+ echo "correct"
+ elif [ "$major_version" = "21" ]; then
+ echo "wrong_distribution"
+ else
+ echo "wrong_version"
+ fi
+ else
+ echo "not_installed"
+ fi
+}
+
+# =============================================================================
+# Clojure
+# =============================================================================
+
+get_clojure_version() {
+ if has_tool clojure; then
+ clojure --version 2>&1 | head -n 1
+ else
+ echo ""
+ fi
+}
+
+get_required_clojure_version() {
+ if [ -f "deps.edn" ]; then
+ # Extract org.clojure/clojure version from deps.edn
+ grep "org.clojure/clojure" deps.edn | grep ":mvn/version" | sed -E 's/.*"([0-9.]+)".*/\1/' | head -n 1
+ else
+ echo ""
+ fi
+}
+
+# =============================================================================
+# Babashka
+# =============================================================================
+
+get_babashka_version() {
+ if has_tool bb; then
+ bb --version
+ else
+ echo ""
+ fi
+}
+
+# =============================================================================
+# Version Managers
+# =============================================================================
+
+detect_version_managers() {
+ local managers=()
+
+ # nvm - Node Version Manager
+ if [ -d "$HOME/.nvm" ] || [ -n "${NVM_DIR:-}" ] || has_tool nvm; then
+ managers+=("nvm")
+ fi
+
+ # fnm - Fast Node Manager
+ if has_tool fnm || [ -d "$HOME/.fnm" ]; then
+ managers+=("fnm")
+ fi
+
+ # n - Node version management (no subcommands)
+ if has_tool n || [ -d "/usr/local/n" ]; then
+ managers+=("n")
+ fi
+
+ # volta - JavaScript Tool Manager
+ if has_tool volta || [ -d "$HOME/.volta" ]; then
+ managers+=("volta")
+ fi
+
+ # asdf - Extendable version manager (multi-language)
+ if [ -d "$HOME/.asdf" ] || has_tool asdf; then
+ managers+=("asdf")
+ fi
+
+ # mise - Dev tools version manager
+ if has_tool mise || [ -d "$HOME/.local/share/mise" ] || [ -d "$HOME/.mise" ]; then
+ managers+=("mise")
+ fi
+
+ # jenv - Java version manager
+ if [ -d "$HOME/.jenv" ] || has_tool jenv; then
+ managers+=("jenv")
+ fi
+
+ # SDKMAN! - Software Development Kit Manager (Java, Gradle, Maven, etc.)
+ if [ -d "$HOME/.sdkman" ] || [ -n "${SDKMAN_DIR:-}" ]; then
+ managers+=("sdkman")
+ fi
+
+ echo "${managers[@]}"
+}
diff --git a/docs/developers-guide/devenv.md b/docs/developers-guide/devenv.md
index 1f0a6bedf17..cd6cf277a47 100644
--- a/docs/developers-guide/devenv.md
+++ b/docs/developers-guide/devenv.md
@@ -13,12 +13,16 @@ Both components are built and assembled together into a single JAR file. In the
## Quick start
-First, make sure your local dev tooling matches the Metabase requirements. Run:
+**New to the project?** Run the automated setup:
```
-./bin/dev-requirements
+./bin/dev-install
```
+This installs [mise](https://mise.jdx.dev) (a tool version manager), sets up your shell, and installs all required tools (Node.js, Java, Clojure, Yarn, Babashka) at the correct versions. Follow the prompts, then open a new terminal.
+
+**Already have your own setup?** You can check that it meets the requirements with `./bin/dev-requirements`.
+
To spin up a development environment, run:
```
@@ -57,6 +61,56 @@ clojure -M:run
See [backend development](#backend-development).
+## IDE and editor setup
+
+If you use an IDE or editor that runs commands outside your interactive shell (VS Code tasks, Emacs (magit etc.), or IntelliJ run configurations), the tools installed by mise won't be available by default. To fix this, add mise shims to your PATH.
+
+Shims are wrapper scripts that automatically select the correct tool version based on the current directory's `mise.toml`.
+
+First, add this to your shell profile (**.zshrc**, **.bashrc**, **.config/fish/config.fish**):
+
+```bash
+export PATH="$HOME/.local/share/mise/shims:$PATH"
+```
+
+Then configure your editor:
+
+### VS Code
+
+VS Code usually inherits your shell's PATH if you launch it from the terminal. If not, add to your **settings.json**:
+
+```json
+{
+ "terminal.integrated.env.osx": {
+ "PATH": "${env:HOME}/.local/share/mise/shims:${env:PATH}"
+ },
+ "terminal.integrated.env.linux": {
+ "PATH": "${env:HOME}/.local/share/mise/shims:${env:PATH}"
+ }
+}
+```
+
+### Emacs
+
+Add to your Emacs config (**init.el** or **.emacs**):
+
+```elisp
+(add-to-list 'exec-path (expand-file-name "~/.local/share/mise/shims"))
+(setenv "PATH" (concat (expand-file-name "~/.local/share/mise/shims") ":" (getenv "PATH")))
+```
+
+If you use **exec-path-from-shell**, it should pick up the shims automatically after you update your shell profile.
+
+### IntelliJ / Cursive
+
+Go to **Settings → Tools → Terminal** and add to "Environment variables":
+
+```
+PATH=$HOME/.local/share/mise/shims:$PATH
+```
+
+For run configurations, you may also need to set the PATH in the run configuration's environment variables.
+
## Frontend development
We use these technologies for our FE build process to allow us to use modules, es6 syntax, and css variables.
diff --git a/mage/test/mage/core_test.clj b/mage/test/mage/core_test.clj
index b1ceef3e175..18dc1a7a6cd 100644
--- a/mage/test/mage/core_test.clj
+++ b/mage/test/mage/core_test.clj
@@ -1,6 +1,8 @@
(ns mage.core-test
(:require
+ [babashka.fs :as fs]
[babashka.tasks :as bt]
+ [clojure.edn :as edn]
[clojure.string :as str]
[clojure.test :refer [deftest is testing]]
[mage.alias-test]
@@ -41,3 +43,32 @@
(let [result (try (bt/shell {:err :string :out :string} (str "./bin/mage " task-name))
(catch Exception e (:out (:proc (ex-data e)))))]
(is (str/includes? result "The following tasks are available:")))))))
+
+(deftest clojure-versions-match-mise-toml
+ (let [mise-toml (str u/project-root-directory "/mise.toml")
+ mise-content (slurp mise-toml)
+ [_ mise-clj-version] (re-find #"clojure\ *=\ *\"(.*)\"" mise-content)
+
+ deps-edn (str u/project-root-directory "/deps.edn")
+ deps-content (edn/read-string (slurp deps-edn))
+ deps-clj-version (get-in deps-content [:deps 'org.clojure/clojure :mvn/version])
+
+ [earlier-touched last-touched] (sort-by fs/last-modified-time [mise-toml deps-edn])]
+ (is (= deps-clj-version mise-clj-version)
+ (str "The Clojure versions in deps.clj and mise.toml should match. Looks like you edited "
+ last-touched ". Please update " earlier-touched " to match it."))))
+
+(deftest bb-versions-match-mise-toml
+ (let [mise-toml (str u/project-root-directory "/mise.toml")
+ mise-content (slurp mise-toml)
+ [_ mise-bb-version] (re-find #"babashka\ *=\ *\"(.*)\"" mise-content)
+
+ bb-edn (str u/project-root-directory "/bb.edn")
+ bb-content (edn/read-string (slurp bb-edn))
+ bb-bb-version (:min-bb-version bb-content)
+
+ [earlier-touched last-touched] (sort-by fs/last-modified-time [mise-toml bb-edn])]
+ (is (= bb-bb-version mise-bb-version)
+ (str "The Babashka versions in bb.edn and mise.toml should match. Looks like you edited "
+ (fs/relativize u/project-root-directory last-touched)
+ ". Please update " (fs/relativize u/project-root-directory earlier-touched) " to match it."))))
diff --git a/mise.toml b/mise.toml
new file mode 100644
index 00000000000..55054cd3884
--- /dev/null
+++ b/mise.toml
@@ -0,0 +1,108 @@
+#:schema https://mise.jdx.dev/schema/mise.json
+
+# Metabase Development Environment
+# =================================
+#
+# This file defines the tools required for Metabase development.
+# We use mise (https://mise.jdx.dev) to manage tool versions consistently
+# across all development machines.
+#
+# Getting started:
+# 1. Run: ./bin/dev-install
+#
+# The install script handles all the setup.
+# This will install mise, configure your shell, and set up all required tools.
+#
+# IDE/Editor users (not cd'd into the repo):
+# ------------------------------------------
+# If your workflow doesn't involve cd'ing into the repo (e.g., Emacs server,
+# IDE running commands with absolute paths), you have three options:
+#
+# 1. Use mise shims (recommended for IDEs):
+# Add ~/.local/share/mise/shims to your PATH instead of using `mise activate`.
+# Shims determine the correct tool version at runtime based on the command's
+# working directory.
+#
+# 2. Use the -C flag to specify the project directory:
+# mise exec -C /path/to/metabase -- yarn build
+#
+# 3. Set MISE_PROJECT_DIR environment variable:
+# MISE_PROJECT_DIR=/path/to/metabase yarn build
+#
+# For more info, see: docs/developers-guide/devenv.md > 'IDE and editor setup' Section
+
+[settings]
+# Automatically install tools when entering the project directory
+auto_install = true
+
+[env]
+# Add bin/ to PATH so mage and other project scripts are available
+_.path = ["{{ config_root }}/bin"]
+
+# Disable corepack - we use yarn classic installed via mise
+COREPACK_ENABLE_AUTO_PIN = "0"
+
+# =============================================================================
+# Required Tools
+# =============================================================================
+
+[tools]
+# Node.js - for frontend development
+# We pin to a specific version to ensure consistency across the team.
+# This should match .nvmrc for compatibility with other version managers.
+node = "22.13.1"
+
+# Yarn Classic - for package management
+# IMPORTANT: Metabase requires Yarn 1.x (Classic), NOT Yarn 2+ (Berry)
+yarn = "1.22.22"
+
+# Java - for Clojure backend
+# We require Eclipse *Temurin* (AdoptOpenJDK successor) for consistency.
+java = "temurin-21.0.9+10.0.LTS"
+
+# Clojure CLI - for backend development and REPL
+clojure = "1.12.3"
+
+# Babashka
+babashka = "1.12.212"
+
+# =============================================================================
+# Other Tools (quality of life)
+# =============================================================================
+#
+# Project-required tools belong here.
+# Anything custom should go to your personal mise.local.toml file (gitignored 👻)
+#
+# See: https://mise.jdx.dev/registry.html#tools
+
+# bat - A cat clone with syntax highlighting
+# https://github.com/sharkdp/bat
+bat = "latest"
+
+# fzf - A fuzzy finder for the terminal
+# https://github.com/junegunn/fzf
+fzf = "latest"
+
+# fd - A fast alternative to find
+# https://github.com/sharkdp/fd
+fd = "latest"
+
+# ripgrep - A fast alternative to grep
+# https://github.com/BurntSushi/ripgrep
+ripgrep = "latest"
+
+# GitHub CLI - for GitHub operations from the terminal
+# https://cli.github.com/
+gh = "latest"
+
+# AWS CLI - for AWS operations
+# https://aws.amazon.com/cli/
+awscli = "latest"
+
+# One Password CLI - for password management
+# https://developer.1password.com/docs/cli/get-started/
+op = "latest"
+
+# jq - Command-line JSON processor
+# https://github.com/jqlang/jq
+jq = "latest"