These are the set of tools which are required in order to complete any build of the Metabase code. Follow the links to download and install them on your own before continuing.
The entire Metabase application is compiled and assembled into a single .jar file which can run on any modern JVM. There is a script which will execute all steps in the process and output the final artifact for you.
./build-uberjar
After running the build script simply look in `target/uberjar` for the output .jar file and you are ready to go.
# Development Environment
Install clojure + npm requirements with
If you plan to work on the Metabase code and make changes then you'll need to understand a few more things.
lein deps
lein npm
### Overview
Build the application JS and CSS with
The Metabase application has two basic compnents:
lein webpack
1. a backend written in Clojure which contains a REST API as well as all the relevant code for talking to databases and processing queries.
2. a frontend written as a Javascript single-page application which provides the web UI.
When developing the frontend client, you'll want to watch for changes,
so run webpack with the '-w' flag.
Both components are built and assembled together into a single jar file which runs the entire application.
./node_modules/webpack/bin/webpack.js -w
### 3rd party dependencies
Note that changes to CSS variables will only be picked up when webpack is restarted.
Metabase depends on lots of other 3rd party libraries to run, so as you are developing you'll need to keep those up to date. These don't run automatically during development, so kick them off manually when needed.
## Usage
```sh
# clojure dependencies
$ lein deps
# javascript dependencies
$ npm install
```
Then run the HTTP server with
### Development server (quick start)
Run your backend development server with
lein ring server
Start the frontend build process with
## Unit Tests / Linting
npm run build-hot
Check that the project can compile successfully with
This will get you a full development server running on port :3000 by default.
./build-uberjar
Run the linters with
## Frontend development
We use these technologies for our FE build process to allow us to use modules, es6 syntax, and css variables.
lein eastwood # Clojure linters
lein bikeshed --max-line-length 240
./lint_js.sh # JavaScript linter
- webpack
- babel
- cssnext
Frontend tasks are managed by `npm`. All available tasks can be found in `package.json` under *scripts*.
To build the frontend client without watching for changes, you can use:
```sh
$ npm run build
```
If you're working on the frontend directly, you'll most likely want to reload changes on save, and in the case of React components, do so while maintaining state. To start a build with hot reloading, use:
```sh
$ npm run build-hot
```
Note that at this time if you change CSS variables, those changes will only be picked up when a build is restarted.
There is also an option to reload changes on save without hot reloading if you prefer that.
```sh
$ npm run build-watch
```
#### Unit Tests / Linting
Run unit tests with
lein test
npm run test # Karma
npm run test-e2e # Protractor
By default, the tests only run against the `generic-sql` dataset (an H2 test database).
You can run specify which datasets/drivers to run tests against with the env var `MB_TEST_DATASETS`:
Run the linters with
MB_TEST_DATASETS=generic-sql,mongo lein test
npm run lint
At the time of this writing, the valid datasets are `generic-sql` and `mongo`.
## Documentation
## Backend development
Leiningen and your REPL are the main development tools for the backend. There are some directions below on how to setup your REPL for easier development.
#### Instant Cheatsheet
And of course your Jetty development server is available via
Start up an instant cheatsheet for the project + dependencies by running
lein ring server
lein instant-cheatsheet
#### Marginalia
#### Unit Tests / Linting
Available at http://metabase.github.io/metabase-init/.
Run unit tests with
You can generate and view documentation with
lein test
lein marg
open ./docs/uberdoc.html
or a specific test with
You can update the GitHub pages documentation using
lein test metabase.api.session-test
make dox
By default, the tests only run against the `h2` dataset (built-in test database). You can specify which datasets/drivers to run tests against with the env var `MB_TEST_DATASETS`:
You should be on the `master` branch without any uncommited local changes before doing so. Also, make sure you've fetched the branch `gh-pages` and can push it back to `origin`.
MB_TEST_DATASETS=h2,postgres,mysql,mongo lein test
At the time of this writing, the valid datasets are `h2`, `postgres`, `mysql`, and `mongo`.
Run the linters with
lein eastwood # Clojure linters
lein bikeshed --max-line-length 240
## Bootstrapping (for Development)
#### Bootstrapping (for REPL)
To quickly get your dev environment set up, use the `bootstrap` function to create a new User and Organization.
Open a REPL in Emacs or with `lein repl` and enter the following:
...
...
@@ -100,7 +148,7 @@ Open a REPL in Emacs or with `lein repl` and enter the following:
You'll be walked through the steps to get started.
## API Client (for Development)
#### API Client (for REPL)
You can make API calls from the REPL using `metabase.http-client`:
...
...
@@ -116,7 +164,7 @@ You can make API calls from the REPL using `metabase.http-client`:
;; ...}
```
## Developing with Emacs
#### Developing with Emacs
`.dir-locals.el` contains some Emacs Lisp that tells `clojure-mode` how to indent Metabase macros and which arguments are docstrings. Whenever this file is updated,
Emacs will ask you if the code is safe to load. You can answer `!` to save it as safe.
...
...
@@ -130,7 +178,7 @@ You'll probably want to tell Emacs to store customizations in a different file.
(load-filecustom-file))
```
## Checking for Out-of-Date Dependencies
#### Checking for Out-of-Date Dependencies
lein ancient # list all out-of-date dependencies
lein ancient latest lein-ring # list latest version of artifact lein-ring
...
...
@@ -141,6 +189,33 @@ Once's this repo is made public, this Clojars badge will work and show the statu
Start up an instant cheatsheet for the project + dependencies by running
lein instant-cheatsheet
#### Marginalia
Available at http://metabase.github.io/metabase-init/.
You can generate and view documentation with
lein marg
open ./docs/uberdoc.html
You can update the GitHub pages documentation using
make dox
You should be on the `master` branch without any uncommited local changes before doing so. Also, make sure you've fetched the branch `gh-pages` and can push it back to `origin`.
# Contributing
In general, we like to have an open issue for every pull request as a place to discuss the nature of any bug or proposed improvement. Each pull request should address a single issue, and contain both the fix as well as a description of how the pull request and tests that validate that the PR fixes the issue in question.
