BlueGenes

BlueGenes is a new user interface to InterMine replacing the JSP-based webapp included with the InterMine server. It runs as its own service and utilises the InterMine web service API.

Running BlueGenes

note

This is a guide to running BlueGenes in a production environment. If you wish to simply try it out, click here to see how to start it from Gradle.

The recommended way to run BlueGenes in production is by using Docker. On every release, a prebuilt image is pushed to dockerhub. The latest version can be downloaded by doing a pull:

docker pull intermine/bluegenes:latest

You should define the environment of your InterMine by creating a bluegenes.env file.

BLUEGENES_DEFAULT_SERVICE_ROOT=https://mymine.org/mymine

BLUEGENES_DEFAULT_MINE_NAME=MyMine

BLUEGENES_DEFAULT_NAMESPACE=mymine

These are the essentials. For more configuration options, see Configuration.

You will want to keep your tools folder outside the container, so that your existing tools will be kept when updating BlueGenes. To do this, run mkdir tools to create a folder we'll use as a docker bind mount. Then start the docker container with the following command:

docker run -p 5000:5000 --env-file bluegenes.env -v "$(pwd)"/tools:/tools -d --restart unless-stopped intermine/bluegenes

You should be able to access BlueGenes from http://localhost:5000. To make it publicly accessible, you can point a reverse proxy to this port, or use a different port on the host (e.g. -p 80:5000).

Essential docker commands

• docker ps -a - List all containers
• docker logs <container> - Print logs of a container
• docker stop <container> - Stop a container
• docker rm <container> - Remove a container
• docker images - List images available locally

Configuration

Environment variable	Description	Default
SERVER_PORT	Port to be used by BlueGenes web server	5000
LOGGING_LEVEL	Minimum level for logging	info
GOOGLE_ANALYTICS	Google Analytics tracking ID	nil
BLUEGENES_TOOL_PATH	Directory on server where BlueGenes tools are installed	./tools
BLUEGENES_DEPLOY_PATH	Custom URL path to host BlueGenes. Must start with / and not end with /, e.g. /bluegenes. If you wish to host at root, set to nil.	nil
BLUEGENES_BACKEND_SERVICE_ROOT	Override service root for backend API requests (usually an internal address)	nil
BLUEGENES_DEFAULT_SERVICE_ROOT	Default InterMine service to run HTTP requests against	https://www.flymine.org/flymine
BLUEGENES_DEFAULT_MINE_NAME	Mine name to display for default mine	FlyMine
BLUEGENES_DEFAULT_NAMESPACE	Namespace of the default mine	flymine
BLUEGENES_ADDITIONAL_MINES	Additional mines managed by this BlueGenes instance (more info)	[]
HIDE_REGISTRY_MINES	Disable acquiring and displaying mines from the public InterMine registry	false

Proxy requests to InterMine web service paths

This is required if you want to host the InterMine web services on the same address as BlueGenes. You will need to configure the following reverse proxy rules, replacing yourmine with the deploy path of your mine:

~ ^/([A-z0-9\-]+\.(xml|txt))$ -> /var/www/yourmine/$1

/ -> bluegenes-server:5000/

/yourmine/service -> tomcat-server:8080/yourmine/service

/yourmine/model -> tomcat-server:8080/yourmine/model

/yourmine/portal.do -> tomcat-server:8080/yourmine/portal.do

/yourmine/run.do -> tomcat-server:8080/yourmine/run.do

/query -> tomcat-server:8080/yourmine

note

/query is required for linking in to the old webapp.

Additional mines

BlueGenes allows you to quickly switch between mines using a dropdown in the navbar. This will display mines from the InterMine Registry (unless HIDE_REGISTRY_MINES is set) but you can also specify your own mines to be shown as a distinct group, usually for other mines of your organisation. This allows you to have a single BlueGenes server work as a front end to multiple mines, without having to run a separate BlueGenes server for each mine in your organisation.

note

Specifying additional mines is also required for permanent URL resolution and web pages markup to work for other mines not defined as the default mine.

BLUEGENES_ADDITIONAL_MINES expects a value encoded in EDN. In short, square brackets denote a sequence of values, while curly braces denote key-value pairs for every two elements. Keys in maps are keywords, which start with a colon followed by characters. Comma is treated as whitespace, and whitespace separates elements.

Below is an examples of HumanMine and FlyMine specified as additional mines.

BLUEGENES_ADDITIONAL_MINES=[{:root "https://www.humanmine.org/humanmine", :name "HumanMine", :namespace "humanmine"} {:root "https://www.flymine.org/flymine", :name "FlyMine", :namespace "flymine"}]

Resources

You can add new or override existing resources served by BlueGenes by creating a resources directory and having docker mount it and added to the Java class path with the following command:

docker run -p 5000:5000 --env-file bluegenes.env -v "$(pwd)"/tools:/tools -v "$(pwd)"/resources:/resources -d --restart unless-stopped --entrypoint /usr/bin/java intermine/bluegenes -cp "resources:bluegenes.jar" bluegenes.core

The path inside the resources directory should match what is provided in BlueGenes, meaning everything inside resources/public is served from the web server root.