Skip to content

Installation Guide

Get OpenGenomeBrowser running in 10 minutes!

In order to run OpenGenomeBrowser with your own data you will have to prepare your files as described below.

License

A license is required to run OpenGenomeBrowser. If you are interested in getting a license, please contact us to request a free trial.

Prerequisites

Note: ensure you have a current version of docker! System repositories tend to be out of date!

Clone the OpenGenomeBrowser docker template

git clone https://github.com/Abrinca/opengenomebrowser-docker-template.git
cd opengenomebrowser-docker-template

Download demo folder_structure

./download_demo_db.sh

... or use your own folder_structure, of course! Read the documentation on how to do that.

Run Docker Compose

Ensure you are logged into the Abrinca Docker repository:

$ docker login docker.abrinca.com
Username: <your license account>
Password: <your license key>

Start the containers:

docker compose -f production-template.yaml up

Open https://localhost/, ignore the self-signed certificate, and you should see this message: "Access Restricted: No Valid License Found".

Connect to the OpenGenomeBrowser container

In a seperate terminal, run:

# open terminal in Docker container
docker exec -ti opengenomebrowser_web bash

# log in as user
$docker (root)# sudo -u user --preserve-env bash

Create superuser and log in

In the terminal from before, run:

# create django administrator account
$docker (user)# python manage.py createsuperuser

Open (https://localhost/admin/) and log in with your superuser account.

Activate OpenGenomeBrowser

Now that you are logged in with the superuser account, activate your license as described here.

Load the folder structure into the database

In the terminal from before, run:

# import organisms and genomes
$docker (user)# python db_setup/manage_ogb.py import-folder-structure

# import ortholog annotations
$docker (user)# python db_setup/manage_ogb.py import-orthologs

# import pathway maps
$docker (user)# python db_setup/manage_ogb.py import-pathway-maps

Congratulations, OpenGenomeBrowser is ready! (Example: https://localhost/pathway/?map=kornec00400&g1=@tax:Bacteria)

Get ready for production

  • Replace the certificates in nginx/certs with proper ones
  • Adapt nginx/nginx.conf accordingly
  • Change the production-template.env:
    • add your own DJANGO_SECRET_KEY (generate one using bash: $(date | sha256sum | base64 | head -c 60))
    • change DJANGO_ALLOWED_HOSTS to your domain (e.g. demo.abrinca.com)
    • ensure USER_ID and GROUP_ID are correct. It mostly influences the permissions a file created by OpenGenomeBrowser will have. This is the command to get the current users uid/gid: id -u/id -g.
    • to increase the time allowed for calculations, change HARAKIRI and uwsgi_read_timeout in nginx/nginx.conf

See also Environment Configuration for more details.

Apply updates

Updates are very simple to install. Simply stop the running container, login to docker.abrinca.com pull the latest

# stop OpenGenomeBrowser (Ctrl+C)
# pull newest image
docker pull docker.abrinca.com/opengenomebrowser
# start OpenGenomeBrowser
docker compose -f production-template.yaml up

From time to time, something like the following message may appear:

The folder structure needs to be updated to match OpenGenomeBrowser code.
Current version: 1, expected: 2
Use the script update_folder_structure from the package opengenomebrowser_tools to perform the upgrade!

It means that the folder structure requires certain changes to be compatible with the new version of OpenGenomeBrowser. These changes can be applied using the function update_folder_structure from the opengenomebrowser-tools.