Difference between revisions of "Team:USTC-Software/Installation"

Biohub 2.0 is an open-source project and allow anyone to do anything with it, as long as not to break GPL 3.0 license. Since it has been developed, tested and deployed on Ubuntu 16.04, we recommend you to use similar operating system to avoid possible problems.

System Requirements

• python >= 3.5. Related packages: python3, python3.5-dev. (libbz2-dev, zlib1g-dev are required if you compile python from source code).
• mysql >= 5.7. Related packages: mysql-server, mysql-client, libmysqlclient.
• redis. Related packages: redis-server.
• jre. Related packages: default-jre.
• elasticsearch < 3. Can be downloaded via: https://download.elastic.co/elasticsearch/release/org/elasticsearch/distribution/deb/elasticsearch/2.4.6/elasticsearch-2.4.6.deb
• nodejs >= 6. Related packages: nodejs.

Clone and Init the Environment

To clone down Biohub 2.0, simply run:

$ git clone https://github.com/igemsoftware2017/USTC-Software-2017
$ cd USTC-Software-2017
$ git submodule update --init --recursive

We recommend to use virtual environment to manage python dependencies:

$ python3 -m venv .env
$ source .env/bin/activate
(.env) $ pip install -r requirements/dev.txt

Setting up the server

The main configuration file should lie at ~/config.json. You can finish it with the help of ~/config.json.example:

{
    "DATABASE": {
        "NAME": "",     // database name
        "USER": "",     // database username
        "PASSWORD": "", // database password
        "HOST": "",     // database host, here should be "localhost"
        "PORT": 3306,   // database port
        "TEST": {       // test database
            "NAME": "",
            "CHARSET": "utf8",
            "COLLATION": null,
            "MIRROR": null
        }
    },
    "PLUGINS": [        // list of installed plugins
        "biohub.abacus",
        "biohub.biocircuit",
        "biohub.biomap"
    ],
    "TIMEZONE": "UTC",
    "UPLOAD_DIR": "",   // path to directory where uploaded files are placed
    "REDIS_URI": "",    // redis connection URL. format "redis://<username>:<password>@<host>:6379"
    "SECRET_KEY": "",   // secret key of the site
    "MAX_TASKS": 20,    // the maximum number of tasks can be executed at a time
    "TASK_MAX_TIMEOUT": 180,  // the maximum seconds a task can be executed
    "ES_URL": "http://127.0.0.1:9200/", // the connection URL of ElasticSearch
    "EMAIL": {          // email configuration
        "HOST_PASSWORD": "",
        "HOST_USER": "",
        "HOST": "",
        "PORT": 465
    },
    "CORS": [],         // authenticated domains. fill the field if cross-domain issues occur during debugging
    "THROTTLE": {       // throttle configuration for each modules
        "rate": 15,
        "experience": 86400,
        "post": 15,
        "vote": 15,
        "register": 3600
    }
}

Then run ./biohub-cli.py init to initialize the database. This step may take several minutes as it will download and preprocess the initial data. After that you can run ./biohub-cli.py runserver to test if the server can be normally started.

About ABACUS

The integrated plugin ABACUS is actually constituted by two parts: the executable, written in Java and not hosted on Github, and the caller, written in Python and located in biohub/abacus/. Due to some technical reasons, we cannot provide the executable. If you want to test ABACUS locally, you may use one of our remote servers by writing the following content to biohub/abacus/config.json:

{
    "ABACUS_REMOTE_SERVERS": [
        "http://106.15.205.191/"
    ]
}

Setting up the frontend

The frontend of Biohub 2.0 lies in frontend/main. Firstly you should install the dependencies:

$ cd frontend/main
$ npm install

During developing, Biohub 2.0 uses webpack-dev-server for hot-reloading. You should configure the proxies in frontend/main/domain.config.json to make it work properly. As above, an example file is available:

{
    "dev": {
        // during developing, plugins and the main frontend are compiled and served separately
        // the following field maps each plugin to a port where its frontend files served
        // to serve a plugin frontend files, run `npm run dev <port>` in its frontend directory
        "plugins": {
            "biohub.abacus": 10000,
            "biohub.biocircuit": 10001,
            "biohub.biomap": 10002
        },
        // the address to your local developing server
        "proxy_domain": "localhost:8000"
    },
    // configuration for production environment
    // you can simply ignore it
    "prod": {
        "domain": "biohub.technology",
        "static": "https://ustc-software2017-frontend.github.io/Biohub-frontend/dist/assets/"
    }
}

Then run npm run dev, and you can access the site at localhost:8080.

Guidance for Plugin Developers

To create and activate a new plugin, simply run:

(.env) $ ./biohub-cli.py plugin new <plugin_name> --with-frontend
(.env) $ ./biohub-cli.py plugin install <plugin_name>

where <plugin_name> is the dot-separated module name of the plugin (e.g. biohub.abacus). You may type ./biohub-cli.py plugin new --help to find more details.

The second step is to install dependencies for the frontend of the new plugin. Simply run:

(.env) $ cd path/to/your/plugin/frontend
(.env) $ npm install
(.env) $ npm run dev <port>  # randomly choose a number for <port> from 10000~65535

Then compiled files will be served at localhost:<port>. Don’t forget to add a new item in frontend/main/domain.config.json:

{
    "dev": {
        // ...
        plugins: {
            // ...
            "<your_plugin_name>": "<port>"
        }
    }
}

Now you can start to write your own plugin. The templates generated by biohub-cli contains some useful comments, which may help you during developing. Also, you can take our integrated plugins (e.g. biohub.biomap) as references.