Getting Started

This quickstart guide walks through the steps required to run Cyclotron locally.

Pre-Requisites

The following pre-requisites are required:

Node.js and MongoDB are available on Linux, macOS, and Windows. It's possible to run Cyclotron on any of these platforms, although the specific steps may vary.

MongoDB

Installing MongoDB is out of the scope of this guide, but detailed instructions are available for most operating systems.

MongoDB does not have to be installed on the same system as Cyclotron. The connection string in the REST API configuration file must be updated accordingly. Replica sets and authentication are also supported by the MongoDB connection string.

If installing MongoDB locally, ensure it is running before continuing: 

mongod --config /usr/local/etc/mongod.conf

Node.js

  1. Install the latest stable version of Node.js for your system. This should install npm as well.
    2. macOS
    macOS users can install Node.js via Homebrew: 
    brew install node

    Other OSes and package managers may also have packages available for easy installation.

  2. Ensure node and npm are both available before continuing: 
    node -v
npm -v

Downloading

Start by cloning the Cyclotron git repository locally onto your computer. If you don't have git installed, GitHub has a nice guide: Set Up Git. On Windows, GitHub for Windows is an easy way to install git.

Alternatively, download a ZIP archive of the repository contents and extract it.

Running the API

The REST API is located in the cyclotron-svc/ folder.

  1. Open the cyclotron-svc/ folder in the shell
  2. Install dependencies using npm 
    npm install
    Windows:
    This may need to be run as an Administrator. Open the Node.js Command Prompt as an Administrator and run the command there.
    Windows/macOS/Linux:
    Node-gyp may require certain prerequisites to avoid warnings during npm installation. See platform-specific instructions here.
  3. Create a configuration file at cyclotron-svc/config/config.js. A sample configuration file sample.config.js is provided in the same folder: 
    cp config/sample.config.js config/config.js

    The sample config defaults to using a local MongoDB instance, with authentication disabled. If using a remote MongoDB server or cluster, update the mongodb property accordingly.

    If using Active Directory or LDAP, ensure that the property enableAuth is set to true, and that all the ldap properties are filled in correctly, including the service account username and password.

  4. Start the service in node: 
    node app.js
  5. Open the API documentation in a browser at http://localhost:8077

For more information on the REST API and its configuration, please refer to cyclotron-svc/README.md.

Running the Website

The Cyclotron website is located in the cyclotron-site/ folder.

  1. Open the cyclotron-site/ folder in the shell
  2. Install dependencies using npm 
    npm install
    Windows:
    This may need to be run as an Administrator. Open the Node.js Command Prompt as an Administrator and run the command there.
  3. Install Gulp globally. This is the build system for the website, and only has to be installed once. 
    npm install --global gulp
    Windows/Linux/OS X:
    This may need to be run as an Administrator or with sudo priviledges.
  4. Build the website and start a web server: 
    gulp server

    This compiles the website into the _public folder and starts a local development web server. The website should automatically open in a browser: http://localhost:8080.

    "unable to connect to github.com":
    This may be due to a firewall blocking the *git://* protocol. Run this command to use https instead: 
    git config --global url."https://".insteadOf git://
    Windows:
    Git must be in the PATH to successfully build the website. If using GitHub for Windows, click the Git Shell button to launch a Command Prompt with the updated PATH.

  5. Update the configuration file at _public/js/conf/configService.js as needed. This file was automatically created from sample.configService.js the first time the project is built.

    This sample config defaults to a local Cyclotron-svc instance, with authentication disabled.If authentication has been enabled in the REST API, it must be enabled in this config as well.

For more information on the Cyclotron website and its configuration, please refer to cyclotron-site/README.md.

Using Cyclotron

For more information on creating Dashboards with Cyclotron, click on the Help button on the home page, or in the site header.