Skip to content

Installation

General

The Docker Compose files in this repository contain various configurations for deploying SynBioHub2.

The base configuration, described in docker-compose.yml, is simply SynBioHub2 (SynBioHub1 as frontend and SynBioHub3 as frontend), and its graph database Virtuoso with a health check added.

To run the base configuration:

  1. Before trying to run SynBioHub2 locally on your PC, make sure that you have Docker installed. If you want to download with git so you can download future changes or save your changes to your repository, be sure to also install Git (this is not required, although there may be something unexpected that requires git).

  2. Open the terminal/cmd. You may need to run some commands as administrator/superuser. If you run into any errors, try this first.

  3. Tip for Windows: You need to start the terminal app as admin, and you can't run individual commands as admin like on macOS or Linux.

  4. Tip for macOS/Linux: If your Linux distribution is older, Docker may not automatically add your user to its group. On Linux, this can be fixed by adding your user to the docker group with the sudo usermod -aG docker $USER command. Alternatively, running Docker as sudo docker should always work on both macOS and Linux as long as Docker is running. Docker runs as a service on Linux (sudo systemctl status docker) and as an app on macOS.

  5. Navigate to the directory where you want to install SynBioHub2.

cd directory_name

If you need a refresher on the terminal, feel free to read this article.

  1. Subsequently, enter the following command into your terminal:

bash git clone -b snapshot https://github.com/SynBioHub/SynBioHub2-docker cd SynBioHub2-docker

This downloads a copy of the snapshot branch, which is known to work.

  1. Then, enter the following command to start the local instance of SynBioHub2:

docker-compose -f ./docker-compose.yml up

This is the step where you most likely need to use root. On macOS or Linux, add sudo to the start of the command before typing the rest. On Windows, make sure you are in an admin terminal. If not, open a new terminal as admin, then redo step 3 and come back to step 5.

  1. In your browser, search for localhost:3333, and it'll take you to a setup page when you run it for the very first time. From here, go to the NEXT STEP if you want to continue. If you want to know how to shut down SynBioHub2, continue reading.

  2. The following command stops a local instance of SynBioHub2 (but only if you are in the correct directory, see step 3):

docker-compose -f ./docker-compose.yml down

With SBOLExplorer

You can also run SynBioHub2 by using SBOLExplorer. To add SBOLExplorer, add the docker-compose.explorer.yml to the main Docker Compose file, i.e., for step 5, run the following command:

sysctl -w vm.max_map_count=262144

docker-compose -f ./docker-compose.yml -f ./docker-compose.explorer.yml up

The sysctl -w vm.max_map_count=262144 command runs only on Linux; it is needed for Elasticsearch, a component of SBOLExplorer. It is likely unnecessary on MacOS.

With Plugins

If you are unfamiliar with plugins, please read the docs.

To add plugins to the configuration, change the command mentioned in step 5 to:

docker-compose -f ./docker-compose.yml -f ./docker-compose.explorer.yml -f ./docker-compose.<Plugin 1 File Name>.yml -f ./docker-compose.<Plugin 2 File Name>.yml up

Note that all plugins are added before the up, and each is preceded by -f. For example, to run the configuration with the VisualIgem plugins and the VisualSeqviz plugin, run:

docker-compose -f ./docker-compose.yml -f ./docker-compose.explorer.yml -f ./docker-compose.pluginVisualIgem.yml -f ./docker-compose.pluginVisualSeqviz.yml up

A table of currently available plugins can be found here.

Installation From Source

Installation from source is not recommended for non-contributors due to requiring many dependencies of specific versions.

Follow the instructions on the following GitHub README to install SynBioHub2 locally onto your system.

Next, you should set up your instance before going public