1. Prepare

Docker is the only prerequisite for running GenomeHubs, however, for convenience this quick-start guide assumes that you will be running all steps on Ubuntu 18.04 with git installed and files stored in your home directory.

See docs.docker.com for details on how to install Docker on other operating systems.

Install packages

Install docker.io and git:

$ sudo apt install -y docker.io git
$ sudo usermod -aG docker $USER

Setup a Docker bridge

To allow container-container communication, set up a Docker network bridge (requires a fairly recent version of Docker)

$ docker network create genomehubs-network

Fetch configuration files

Clone the example configuration files from the genomehubs/template repository:

• naming the template directory v1 is convenient for versioning of your site

e93

$ mkdir ~/genomehubs && cd ~/genomehubs
$ git clone https://github.com/genomehubs/template -b 19.05 v1

e89

$ mkdir ~/genomehubs && cd ~/genomehubs
$ git clone https://github.com/genomehubs/template -b 17.06 v1

e85

$ mkdir ~/genomehubs && cd ~/genomehubs
$ git clone https://github.com/genomehubs/template -b 17.03 v1

Quick setup with no public domain

If you are running GenomeHubs on a local machine, the default configuration should just work.

To test on a remote server without configuring an external domain name you can map the required ports to localhost with an entry like this in a .ssh/config file:

$ nano ~/.ssh/config
Host dockerserver
 HostName example.com
 LocalForward 8880 127.0.0.1:8880
 LocalForward 8881 127.0.0.1:8881
 LocalForward 8882 127.0.0.1:8882
 LocalForward 8883 127.0.0.1:8883
 LocalForward 8884 127.0.0.1:8884
 User username

Configure domain names and firewall

Individual GenomeHubs components can be viewed on a localhost, but to make them publicly available you will need to register a domain name and point it to the ip address of the machine that you are using to host the site. You will also need to open up port 80 to allow external access to the GenomeHubs web sites and ensure that requests for each of the GenomeHubs subdomains. These details are beyond the scope of this guide so if you are unsure what to do, ask your local sysadmin.

If you follow the conventions in this guide (substitute your domain name for example.com):

• example.com will need to be directed to port 80 on your host server

• ensembl.example.com will need to be redirected by your host server to point to the EasyMirror Docker container running on port 8081

• download.example.com will need to be redirected by your host server to point to the h5ai Docker container running on port 8082

• blast.example.com will need to be redirected by your host server to point to the SequenceServer Docker container running on port 8083

One way to manage the local redirects is to install and configure lighttpd:

$ sudo apt install -y lighttpd
$ sudo nano /etc/lighttpd/lighttpd.conf

# Append at end of file:
$HTTP["host"] =~ "ensembl.example.com"{
  proxy.server = ("" => ("" => (
    "host" => "127.0.0.1",
    "port" => "8881",
    "fix-redirects" => 1
  )))
}
$HTTP["host"] =~ "download.example.com"{
  proxy.server = ("" => ("" => (
    "host" => "127.0.0.1",
    "port" => "8882",
    "fix-redirects" => 1
  )))
}
$HTTP["host"] =~ "blast.example.com"{
  proxy.server = ("" => ("" => (
    "host" => "127.0.0.1",
    "port" => "8883",
    "fix-redirects" => 1
  )))
}
$HTTP["host"] =~ "search.example.com"{
  proxy.server = ("" => ("" => (
    "host" => "127.0.0.1",
    "port" => "8884",
    "fix-redirects" => 1
  )))
}

$ sudo service lighttpd restart