Development environment

Set up your local development environment for Metabase

The Metabase application has two main components:

1. Backend - Written in Clojure with a REST API for database queries
2. Frontend - JavaScript single-page application providing the web UI

Both components are built and assembled into a single JAR file. This guide will help you set up your development environment to work on either or both.

Quick start

New to the project? Use the automated setup script to install all required tools.

1. Run the automated setup

   The setup script installs mise (a tool version manager) and all required dependencies:

   ./bin/dev-install
   

   This installs Node.js, Java, Clojure, Bun, and Babashka at the correct versions. Follow the prompts, then open a new terminal.

2. Verify your setup (optional)

   If you already have your own setup or want to verify everything is configured correctly:

   ./bin/mage doctor
   
3. Start the development environment

   Run both frontend and backend together:

   bun run dev
   

   Or run them separately in two terminal sessions (see below).

Once everything is running, open your browser to http://localhost:3000 to see Metabase.

Prerequisites

If you prefer to install dependencies manually:

Required tools

macOS (Homebrew)

# Install Xcode Command Line Tools first
xcode-select --install

# Install dependencies
brew install clojure
brew install openjdk@21
brew install node
curl -fsSL https://bun.sh/install | bash

Tool versions

• Java - JDK 21 (required)
• Node.js - Latest LTS release
• Clojure - Latest stable version
• Bun - 1.0.0 or higher

If you have multiple JDK versions installed, make sure Java 21 is active:

sudo update-alternatives --config java

Special requirements

Apple M1/M2 computers

Install Rosetta 2 before building the frontend:

/usr/sbin/softwareupdate --install-rosetta --agree-to-license

VS Code / IDE setup

If your IDE runs commands outside your interactive shell, configure mise shims:

IDE configuration for mise

Add to your shell profile (.zshrc, .bashrc, etc.):

export PATH="$HOME/.local/share/mise/shims:$PATH"

VS Code settings.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 init.el:

(add-to-list 'exec-path (expand-file-name "~/.local/share/mise/shims"))
(setenv "PATH" (concat (expand-file-name "~/.local/share/mise/shims") ":" (getenv "PATH")))

Frontend development

The frontend uses Bun for package management and rspack for bundling.

Install dependencies

bun install

Build commands

Hot reload (recommended)

bun run build-hot

Frontend testing

All tests

bun run test

Debugging tips

Better source maps

For improved debugging with breakpoints in JSX:

BETTER_SOURCE_MAPS=true bun run dev

Enable ESLint in dev mode

By default, ESLint is disabled during development for faster builds:

USE_ESLINT=true bun run build-hot

Backend development

The backend is written in Clojure and runs on the JVM.

Start the backend server

clojure -M:run

The server will start at http://localhost:3000. Wait for the message “Metabase initialization complete.”

Using the REPL

The Clojure REPL is the primary development tool for backend work:

clojure -M:repl

Once in the REPL, start the server:

(do (dev) (start!))

Application database

By default, Metabase uses H2. For development, we recommend PostgreSQL.

Configure PostgreSQL for development

Create ~/.clojure/deps.edn:

{:aliases
 {:user
  {:jvm-opts
   ["-Dmb.db.host=localhost"
    "-Dmb.db.type=postgres"
    "-Dmb.db.user=<username>"
    "-Dmb.db.dbname=<dbname>"
    "-Dmb.db.pass="]}}}

Or use a connection string:

["-Dmb.db.connection.uri=postgres://<user>:<password>@localhost:5432/<dbname>"]

Or create a .lein-env file in the project directory:

{:mb-db-type   "postgres"
 :mb-db-host   "localhost"
 :mb-db-user   "<username>"
 :mb-db-dbname "<dbname>"
 :mb-db-pass   ""}

Building drivers

Database drivers live in the modules/drivers/ directory and must be built separately:

Build all drivers

./bin/build-drivers.sh

Driver JARs are placed in the plugins/ directory.

Running backend tests

OSS tests

clojure -X:dev:test

Testing with specific drivers

By default, tests run against H2. To test other drivers:

DRIVERS=h2,postgres,mysql clojure -X:dev:drivers:drivers-dev:test

Running linters

clj-kondo

mage kondo

Running multiple instances

To run multiple Metabase instances on the same machine:

Frontend

MB_FRONTEND_DEV_PORT=8089 MB_EDITION=ee bun run build-hot

Backend

MB_JETTY_PORT=3001 MB_FRONTEND_DEV_PORT=8089 clojure -M:run

Continuous integration

Run all linters and tests:

All tests

bun run ci

Configuration files

To skip the setup wizard and pre-configure your instance, add a Metabase config file to the directory where you run Metabase.

Troubleshooting

File watching issues

If your system has trouble detecting file changes, enable filesystem polling in rspack.main.config.js:

watchOptions: {
  poll: true
}

Then tell git to ignore the change:

git update-index --assume-unchanged rspack.main.config.js

Port conflicts

If port 3000 is already in use, set a different port:

MB_JETTY_PORT=3001 clojure -M:run

Next steps

• Learn about the code structure
• Read the testing guide
• Understand how to build drivers