Getting Started
This quickstart guide walks through the steps required to run Cyclotron locally.
Pre-Requisites
The following pre-requisites are required:
- MongoDB
- Node.js
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
- Install the latest stable version of Node.js for your system. This should install npm as well.
- Ensure node and npm are both available before continuing:
node -v npm -v
Other OSes and package managers may also have packages available for easy installation.
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.
- Open the
cyclotron-svc/
folder in the shell - 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. - Create a configuration file at
cyclotron-svc/config/config.js
. A sample configuration filesample.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 theldap
properties are filled in correctly, including the service account username and password. - Start the service in node:
node app.js
- 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.
- Open the
cyclotron-site/
folder in the shell - 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. - 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. - 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. -
Update the configuration file at
_public/js/conf/configService.js
as needed. This file was automatically created fromsample.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.