Quick Start for Developers

Openframe Developers Quick Start Guide

Overview

This document outlines some basic info about the structure and code base of the Openframe project, and provides details about setting up for local development.

Design Notes

There are two main components to the Openframe code base — the API server and the frame controller. At present, the API server also serves the web app (though this is likely to change in the future) and by default starts up an instance of the global event bus which the app, server, and frame use to communicate.

The API Server is built on loopback, a node.js framework for building RESTful APIs. It represents the API Server (REST) in the diagram below. The Global Event Bus lives in a separate repository, Openframe-PubSubServer, though as mentioned it is included as a dependency in the API Server repo for simplicity during development.

Running the Server

The codebase was largely written following the loopback docs' recommendations and examples. By default the API server will use an in-memory data store and will generate some dummy data (a few users, a few artworks). To run locally, fork/clone the repo, install the npm dependencies, and run npm start.

# (you'll probably fork the repo, and clone your fork)
$ git clone https://github.com/OpenframeProject/Openframe-APIServer.git
$ cd Openframe-APIServer
$ npm install
$ npm start

This repo includes the pubsub server as a dependency. Running npm start will spin up an instance of the PubSub server on port 8889. If you want to start only the API, run npm run start-api. Likewise, if you want to run only the pubsub server, run npm run start-pubsub.

For DEBUG output, set the DEBUG env var:

# output ALL debug (includes a lot due to loopback)
$ DEBUG=* npm start

# output openframe-specific debug
$ DEBUG=openframe:* npm start

Various environment configuration options can be set using a .env file. An example .env file might specify the host and port on which to expose the API server, configure the datasource, and specify a host and port on which the API server can expect to find the PubSub server. Take a look at the .env.example file in the project root.

# in .env file...
PORT=1234

# indicate how the API server should connect to the pubsub server
PS_HOST='pubsub.openframe.io'
PS_PORT=2345

REST API Docs

Loopback provides auto-generated documentation (via swagger) based on the data model definitions. After starting up the server locally, visit localhost:8888/explorer/ to view the docs and test out the API.