Skip to content

Getting Started

Jump to bottom
David Carroll edited this page Aug 22, 2017 · 3 revisions

Contents

  1. Overview
  2. Getting Platform Resources
  3. Configuration
  4. Overview
  5. Running Using Docker
  6. Running Manually

Please note that this document is a work in progress, with large sections of content missing.

Overview

The Pretzel web platform comprises an ember.js frontend and a node.js with MongoDB backend. Together, they provide the visual, communication, and storage facilities for the platform.

If you are familiar with Docker and Docker Compose, it is recommended that you install Prezel via the steps below, as this simplifies deployment of the platform.

It is anticipated that further work on the Pretzel will simplify Pretzel deployment.

Dependency Versions

Note the core resource versions used to develop Pretzel when submitting an issue for the repo. These versions are likely to change without notice.

Resource Version
Node.js 6.9.5
MongoDB 3.4.5
Docker 17.06.0-ce
Docker Compose 1.14.0

Getting Project Resources

Clone the Github repository with git:

git clone https://github.com/plantinformatics/pretzel.git

Configuration

Before initialising a Pretzel instance, some configuration decisions are required:

# core environment variables
API_PORT_EXT=5000
MONGO_INITDB_ROOT_USERNAME=Test
MONGO_INITDB_ROOT_PASSWORD=Test

#optional for email service
API_HOST=example.com
[email protected]
[email protected]
EMAIL_HOST=smtp.example.com
EMAIL_PORT=25
EMAIL_USER=smtpuser
EMAIL_PASS=smtppass
EMAIL_VERIFY=[NONE, USER, ADMIN]
  • API_PORT_EXT: The port to communicate to the Pretzel instance. Typically, port 80 is assigned when setting the Pretzel instance as a web server for collaboration, otherwise you can pick any port between 0 and 65536.
  • DB_PORT_EXT: The port to communicate to the MongoDB instance externally, if required. Typically, port 27017 is default for MongoDB, but you can assign any port you like as mentioned above.
  • MONGO_INITDB_ROOT_USERNAME / MONGO_INITDB_ROOT_PASSWORD: By default, a user name and password for MongoDB are assigned to avoid automated attacks against unprotected databases. Modify these values to something unique and secure for your own deployment. It is highly recommended that you assign a username and password!

If you wish to enable email validation on your Pretzel instance, the following environment variable configuration is required:

  • API_HOST: To populate email link callbacks, such as password reset requests, and email address confirmations. Assign the IP address or domain name where the Pretzel instance will be accessed. Note that API_PORT_EXT is added to API_HOST when building the callback URL, so the port does not need to be specified here again.

  • EMAIL_ADMIN: To receive email address confirmations if EMAIL_VERIFY=ADMIN. Assign an email address you wish to act as the recipient for verification emails on your Pretzel instance.

  • EMAIL_FROM: To populate email sender data in password reset requests, and email address confirmations. Assign an email address you wish to act as the sender for emails on your Pretzel instance.

  • EMAIL_HOST: Email server for outgoing mail from the Pretzel instance. Assign an SMTP server accessible by the Pretzel instance.

  • EMAIL_PORT: Email server port for outgoing mail from the Pretzel instance. Assign the port of the SMTP server accessible by the Pretzel instance.

  • EMAIL_USER / EMAIL_PASS: Email server username and password. Populate these environment variables when using a mail server with authentication requirements

  • EMAIL_VERIFY: Recipient of verification emails. This gives flexibility to Pretzel instance deployments. Three options are provided:

    • EMAIL_VERIFY=NONE: No email verification of user sign up.
    • EMAIL_VERIFY=USER: User receives verification email on sign up.
    • EMAIL_VERIFY=ADMIN: Administration receives verification email on sign up.

    By default, EMAIL_VERIFY=ADMIN is assumed unless overridden. If EMAIL_VERIFY=ADMIN, make sure to assign an environment variable for EMAIL_ADMIN Assign the intended recipient of verifications for new users.

Refer to the installation methods below for instructions on how to specify these environment variables to launch your Pretzel instance.

Install Using Docker

You can choose to install Pretzel with Docker. This ensures that time spent managing project dependencies and configuration of the platform are minimised. The Dockerfile run with the command below at the root of the Pretzel project is designed to build the project resources and launch the API:

docker build -t pretzel .

When starting the docker container, environment variables can be provided to configure the Pretzel instance for email and databases. Refer to the explanations of the environment variables in the Configuration section.

docker run -e API_PORT_EXT=3000 [more environment configuration here] pretzel

Alternatively, you can start Pretzel in detached mode by adding the -d argument

docker run -e API_PORT_EXT=3000 [more environment configuration here] -d pretzel

Install Manually

Clone the Github repository with git:

git clone https://github.com/plantinformatics/pretzel.git

Dependencies

Database

Install MongoDB using your distribution's package manager; for example, in Ubuntu:

sudo apt-get install mongodb

Node.js and NPM

NPM is the package manager for Node.js and allows easy installation of the tools required by this project. You can install Node.js and NPM using your native distribution package manager; for example, in Ubuntu:

sudo apt-get install nodejs npm

Install Ember dependencies

To install the various plug-ins and add-ons required by the project, use NPM and Bower (for the Ember-specific dependencies):

# cd into Ember directory
cd frontend
# Install Ember dependencies
npm install
bower install
# cd into Express app directory
cd ../backend
# Install dependencies
npm install

Note that npm install in backend/ and frontend/ will install the Express.js and Ember.js dependencies, including Express.js and Ember.js themselves, into those directories. For example, ember is in frontend/node_modules/ember-cli/bin/.

Set-up configs

Ember needs to be pointed to URL of the API in frontend/app/adapters/application.js. Copy default settings from frontend/app/adapters/application.js.example:

cp frontend/app/adapters/application.js.example frontend/app/adapters/application.js

By default, it is assumed that you are running Express and Ember on the same machine (localhost), but change this to reflect your set-up:

# frontend/app/adapters/application.js

import DS from 'ember-data';
import PartialModelAdapter from 'ember-data-partial-model/mixins/adapter';

export default DS.RESTAdapter.extend(PartialModelAdapter, {
  host: 'http://localhost:1776',
});

Running

Starting Express and Ember

You should now be able to start the Express API server:

cd backend
node app.js

And Ember:

cd frontend
./node_modules/ember-cli/bin/ember serve
# or ember s if Ember installed globally

Checking things are running

If the Express API has started correctly, you should see the following if you navigate to http://localhost:1776/geneticmaps in a browser:

{
  "geneticmaps": [],
}

This tells us the API is working (though currently no data has been loaded).

If Ember has started correctly, you should see something like the following in the standard out after running ember serve:

Build successful - 15937ms.

Slowest Trees                                 | Total
----------------------------------------------+---------------------
Babel                                         | 11965ms

Slowest Trees (cumulative)                    | Total (avg)
----------------------------------------------+---------------------
Babel (15)                                    | 14371ms (958 ms)

Navigating to localhost:4200 in a browser, you should see a page load.

HOME

User Guide / Tutorials

Advanced Topics

Clone this wiki locally