Cyclotron is a browser-based platform for creating dashboards. It provides standard boilerplate and plumbing, allowing non-programmers to easily create and edit dashboards using customizable components. It has a built-in dashboard editor, and hosts the dashboards directly.
Dashboards are defined declaratively as a JSON document, which contains all the properties required to render the Dashboard.
- Key Concepts
- Features
- Should I Use Cyclotron?
- Requirements
- Installation
- Deployment
- Extending Cyclotron
- Contributing
- Licensing
-
Dashboard: a series of Pages, as well as Data Sources, Scripts, Styles, and other configurations; stored as a JSON document, it contains all the properties required to render itself
-
Page: one or more Widgets combined in various sizes and layout; one Page is displayed at a time
-
Widget: reusable component that displays on the Dashboard; different types are available
-
Data Source: reusable component that retrieves data for use by Widgets; different types are available
-
Declarative definition of Dashboards, requiring no HTML or JavaScript (although it's optionally available)
-
Included Widgets: chart, table, number, html, javascript, iframe, stoplight, treemap
-
Included Data Sources: JSON, Graphite, Splunk, JavaScript
-
Built-in data loading, filtering, and sorting
-
LDAP/Active Directory Integration
-
Permissions for viewing and editing Dashboards
-
Mobile support
-
REST API access
Cyclotron is best thought of as an alternative to custom, light-weight websites that visualize data. It provides the web hosting, page layout, data loading, and assorted widgets—all without writing code. In contrast, building a comparable website from scratch would require provisioning a server/VM, choosing the appropriate web frameworks and libraries, and writing the code for the site. Cyclotron simplifies this process dramatically, making it ideal for rapid prototyping.
However, Cyclotron has a limited set of built-in Widgets and Data Sources. The HTML and JavaScript Widgets do allow for a wide degree of customization, but require some web development. Cyclotron lacks built-in interactivity, so it may not be ideal for building highly interative websites. It also is designed for building full-screen dashboards, not reports.
In regards to data, Cyclotron does not store or cache any data for Dashboards. Dashboards can load external data through various Data Sources, but it is done on-the-fly when Dashboards are viewed. Cyclotron can do filtering/sorting and custom transformations, but this should not be considered a replacement for ETL jobs. In this regard, Cyclotron is ideal as a front-end for an existing database or web service.
- Node.js
- MongoDB
- (Optional) Any web server--Nginx, Apache, IIS, etc
Node.js and MongoDB are available on Linux, OS X, and Windows, so it should be possible to run Cyclotron on any of these platforms, although the specific steps may vary.
These installation instructions are primarily intended for development and testing purposes. Refer to the Deployment section for more details on server deployment.
Start by cloning this 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.
Install MongoDB according to the installation instructions for your system. Cyclotron automatically creates the MongoDB database on startup MongoDB server, so no other configuration needs to be done.
MongoDB does not have to be installed on the same system as the Cyclotron website or service, as long as the connection property is updated accordingly. Replica sets and authentication are also supported.
Ensure MongoDB is running before continuing:
mongod --config /usr/local/etc/mongod.conf
Install the latest stable version of Node.js for your system. This should install npm as well.
Packages may be available separately for your system, depending on the OS and package manager.
The cyclotron-svc/
folder contains the REST API for Cyclotron, which interfaces with MongoDB.
-
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.
-
Create a configuration file at
cyclotron-svc/config/config.js
. A sample configuration filesample.config.js
is provided: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 used to validate logins. -
Start the service in node:
node app.js
-
To verify the service is running, 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.
The cyclotron-site/
folder contains the website for Cyclotron.
-
Open the
cyclotron-site/
folder in the shell -
Install all 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 done once.
npm install --global gulp
Windows/Linux/OSX: this may need to be run as an Administrator or with sudo priviledges.
-
Build and run the service:
gulp server
This compiles the website into the
_public
folder and starts a local development web server. The website should automatically open: http://localhost:8080."unable to connect to github.com": this may be due to a firewall blocking the git:// protocol. Run this:
git config --global url."https://".insteadOf git://
Windows: Git must be in the PATH to successfully build the website; if using GitHub for Windows, just open the Git Shell which automatically adds it.
-
Update the configuration file at
_public/js/conf/configService.js
as needed. Gulp automatically populates this file fromsample.configService.js
if it does not exist.The sample config defaults to using 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, please refer to cyclotron-site/README.md.
For specific details on deployment, please refer to cyclotron-site/README.md and cyclotron-svc/README.md.
More information on extending Cyclotron is available in EXTENDING.md
We gladly accept contributions to Cyclotron in the form of issues, feature requests, and pull requests! Check out CONTRIBUTING.md for more information.
Cyclotron is licensed under the MIT license; refer to LICENSE for the complete text.
Cyclotron has a dependency on Highcharts, a commercial JavaScript charting library. Highcharts offers both a commercial license as well as a free non-commercial license. Please review the licensing options and terms before using this software, as the Cyclotron license neither provides nor implies a license for Highcharts.
The only feature depending on Highcharts is the Chart widget, so both can be removed if necessary.