Headless Octopus

A tool for starting Node.js projects more quickly and adding "listener" functionality to listen to objects as they are being saved and execute functions based on changes.

Index

• Installation
• Project Setup
• Running the Server
• Adding API Endpoints
• Sending Emails
• Utilities

Installation

1. Clone this repo into a subdirectory of your project, like so:

 ┬ my-project
 └─── headless-octopus

2. Run the following bash command, substituting headless-octopus for whatever name you gave the repo when you cloned it:

npm install --prefix headless-octopus/

3. Set up the settings file and packages directory from the Project Setup instructions below.

Project Setup

The headless-octopus repo is currently designed to run with its rules and custom api configuration stored in a sibling directory, following a structure similar to this:

 ┬ my-project
 ├─── headless-octopus
 ├──┬ packages
 │  ├──┬ rules
 │  │  ├─── first-rule.js
 │  │  └─── second-rule.js
 │  └──┬ myPackage
 │     ├─── api.js
 │     └──┬ rules
 │        ├─── first-package-rule.js
 │        └─── second-package-rule.js
 ├─── settings.js
 └─── run.js

In the above, the run.js file is specifically for starting the server, which can be done with two lines, using the above structure as an example:

"use strict";
let octoServer = require('./headless-octopus/server.js');
octoServer.start();

This starts the server up, importing the setting.js module (if one exists). The settings.js module should be an object that contains general, non-sensitive configuration settings for the server. For example, the following

Running the Server

It should be noted that there is use of spread operators in Headless Octopus, therefore when the server is run, it needs to be run similarly to this:

node --harmony run run.js

Adding API Endpoints

As hinted at by the example structure above, API endpoints are created by adding a file named api.js inside of a "package" (a directory within the packages directory).

An api.js file can export an object with methods, in which case each method has its own endpoint at /api/<package>/<method>, where <package> is the name of your "package" directory ("myPackage" in the example above) and <method> is the property name of each method in the object that api.js exports.

However, it is also possible for the api.js file to export a single function, in which case the endpoint /api/<package> is created using the function that api.js exports.

Sending Emails

By default, headless-octopus servers have sendmail as a requirement for quick-n-dirty email sending. You can access it from the global variable, send_mail. Here's a basic example of sending an email:

send_mail({
  from: 'Headless Octopus <[email protected]',
  to: '[email protected]',
  subject: 'Testing Email',
  html: '<h1>Test</h1> <p>This is a test email</p>',
});

For more examples, please check out the official sendmail examples.

Utilities

There are a few utility modules to make working with Headless Octopus easier:

• google-utils