Start by installing the dependencies in System Requirements, then Download NPM dependencies and finally, run the command in Running a dev environment. For more information, refer to the rest of this document or the FAQ.
node -v
. We recommend installing node using nvmnpm install
These commands are explained in more depth below, but if you know what you want, here's a quick reference of the most useful ones.
lein dev # start dev server with hot-reloading
lein repl # start dev server with hot-reloading and nrepl (no clean or css)
lein prod # start prod server
lein deploy # build prod release and deploy to clojars
lein format # run cljfmt to fix code indentation
lein kaocha # run unit tests
npx cypress run # run cypress ui tests
You can start a complete developer environment with automatic compilation of Less CSS and hot-reloading of code changes by running:
lein dev
However, all the output will be thrown into one terminal. If you wish to keep the processes separate, you can start them individually by following the instructions below.
We use less to write our styles.
You can compile the Less sources to CSS with the command below:
lein less
It will run in watch mode, recompiling the CSS after every change until you exit it with Ctrl+C. The browser page will automatically reload the updated CSS.
lein figwheel dev
Note: if you use lein run
or any alias calling it like dev
or repl
, Figwheel will be started automatically.
If you have OpenJDK 8, run this command:
lein with-profile +dev run
If you have OpenJDK 9, run this command:
lein with-profile +java9 figwheel
By default, the web server will be started on http://localhost:5000/. To change this value, edit the corresponding config.edn
.
You can run the ClojureScript unit tests by invoking the test runner kaocha.
lein kaocha
Kaocha also has a watch mode that's useful when editing the tests.
lein kaocha --watch
If you need something faster, evaluating (cljs.test/run-tests)
from a connected editor would be even better. Although with async tests, you'll need some way of having your editor report the results.
Checklist:
Start BlueGenes connected to your local Biotestmine by using the command below. If your local Biotestmine runs on a different address than http://localhost:9999/biotestmine, you can specify it with the BLUEGENES_DEFAULT_SERVICE_ROOT
envvar.
lein biotestmine
Run all the Cypress tests:
npx cypress run
Cypress also has a really useful interface for debugging failing tests:
DEBUG=cypress:* npx cypress open
Tip: You can also run the Cypress tests with BlueGenes deployed to a custom deploy path by editing cypress.json baseUrl
key to include the path (e.g. "http://localhost:5000/foo/bar"
) and passing the same path as an envvar, BLUEGENES_DEPLOY_PATH=/foo/bar lein biotestmine
Most of the time, we develop with uncompressed files since it's faster for hot reloads. But for production, we want things to be extra fast on load and we don't hot-reload changes, so it's better to present minified files that have had all un-necessary code stripped. Clojure uses Google Closure tools (yes, Clojure uses Closure) to minify things.
Sometimes the Closure compiler is overzealous and removes something we actually want to keep. To check what your work looks like in a minified build, run this in the terminal (I'd recommend closing any existing lein run / lein figwheel sessions first).
lein with-profile prod cljsbuild once min
lein with-profile prod run
There is also a shortcut that in addition, cleans and compiles CSS.
lein prod
BlueGenes has a Dockerfile which you can build with a fresh uberjar.
lein uberjar
docker build -t bluegenes .
Run it and the web server should default to port 5000.
docker run -p 5000:5000 -it --rm bluegenes
You can specify environment variables by using the -e
or --env-file
arguments when calling docker. See Configuring for a list of all available environment variables.
There is also a prebuilt docker image available on Docker Hub.
docker pull intermine/bluegenes:latest
For an example of running BlueGenes in docker for a production environment, start by creating a bluegenes.env
file.
BLUEGENES_DEFAULT_SERVICE_ROOT=https://mymine.org/mymine
BLUEGENES_DEFAULT_MINE_NAME=MyMine
BLUEGENES_DEFAULT_NAMESPACE=mymine
Once you have added all your environment variables, start the docker container.
docker run -p 5000:5000 --env-file bluegenes.env -v "$(pwd)"/tools:/tools -d --restart unless-stopped bluegenes
This will create a tools
folder in the current directory mounted as a docker bind mount. This is so your tools can be persisted when changing BlueGenes versions and to facilitate manual modification of tools.
Dokku allows you to push a Git branch and have it automatically build and serve it using the appropriate docker container. (You can also use BlueGenes with heroku.)
Once dokku is configured on your remote host, you'll need to add your public key, create a remote for your host and push to it:
# On your dokku host
sudo dokku ssh-keys:add your-user /path/to/your/public/key
# On your dev computer
git remote add dokku dokku@your-host:bluegenes
git push dokku master
If you want to deploy a different branch, you can use git push dokku dev:master
(replace dev with the branch you wish to deploy from) instead.
You can also deploy docker images that you build locally, to the dokku instance. This is useful since it's much quicker and avoids the extra load on the dokku server from building.
Make sure youruser
on dokku-server
is part of the docker
group. This allows you to stream the file instead of manually transferring it through ssh.
lein uberjar
docker build -t dokku/appname:v1 .
docker save dokku/appname:v1 | bzip2 | ssh youruser@dokku-server "bunzip2 | docker load"
ssh youruser@dokku-server
sudo dokku tags:deploy appname v1
Note that the tag v1
needs to be unique for each deployment. It is common to use a version string and increment it for each deployment (might not necessarily correspond with version releases). See the dokku documentation for more information.
It's also possible to compile BlueGenes to a jar that will automatically launch a server when executed.
To compile and package BlueGenes into an executable jar, run the following command in the project folder:
lein uberjar
Then, to start the application, execute the jar and pass in a config.edn
file like so:
java -jar -Dconfig="config/prod/config.edn" target/bluegenes.jar
For security reasons, the config.edn
file used to execute the jar can be located anywhere, including your home directory.
You can alternatively bundle config/prod/config.edn
into the uberjar by including the prod profile:
lein with-profile prod uberjar
InterMine 2.0 includes a Gradle target to launch a BlueGenes instance.
By default, it launches the latest BlueGenes release from Clojars. If you want to update the version of the JAR being launched, you'll need to create an uberjar (see above).
Official BlueGenes releases can be deployed to Clojars, under the org.intermine Clojars organisation.
When deploying BlueGenes to Clojars, the JAR file should include all compiled assets. This includes JavaScript, less, and vendor libraries. This allows other projects to include BlueGenes as a dependency and deploy the client and server without needing to compile BlueGenes.
To deploy a compiled JAR to Clojars, simply use the deploy
alias which automatically includes the uberjar
profile and targets Clojars.
$ lein deploy
git tag -a v1.0.0 -m "Release v1.0.0"
, replacing 1.0.0 with your version number.git push origin
followed by git push origin v1.0.0
(again, replace 1.0.0 with your version number). Make sure that you push to the intermine repository, not just your fork!lein deploy
.lein uberjar
docker build -t bluegenes .
docker tag bluegenes intermine/bluegenes:1.0.0
(remember to use your correct version number)docker tag bluegenes intermine/bluegenes:latest
docker push intermine/bluegenes:1.0.0
docker push intermine/bluegenes:latest
git push dokku dev:master
.dev
is our main development branch, whereas master
is our production branch.intermine_version
in the InterMine registry. The changelog for InterMine release versions is available on GitHub.If none of these tips help you, create an issue or contact us (via chat, email, mailing list, etc.).
Can you improve this documentation? These fine people already did:
uosl, Herald, Leandro Doctors, SanniM3 & Yo YehudiEdit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close