Installation

SockBot is written entirely in JavaScript using ES6 syntax. As such it is compatible with Node.js >= 0.11 and io.js >= 1.7. Sockbot is tested on Linux against several versions of each environment and should function correctly on Windows and Mac as well.

Environment setup

Sockbot requires a recent version of either io.js or Node.js with working npm to function.

Required software:

  • Node.js version 0.11 or greater (version 0.12.5 or greater recommended)

or

  • io.js version 1.7 or greater (version 2.4 or greater recommended)

Installation

Basic installation of SockBot can be accomplished by cloning our repository from GitHub or by downloading one of our releases. SockBot can also be installed via installing our npm package

Cloning our repository

Cloning our repository is a quick way to get started with SockBot.

Execute the following command in a terminal to clone SockBot to your machine.

git clone https://github.com/SockDrawer/SockBot.git

To update an existing clone to the latest version of SockBot execute the following command in the same folder that SockBot was cloned into.

git pull

Downloading a release

If you don't have access to Git you can visit our releases page on GitHub and download one of our releases. After downloading a release extract the archive to a folder on your machine to complete installation.

Installing via npm

SockBot can also be installed via npm, for integration with another project or to install SockBot globally for a machine.

To install sockbot via npm execute the following command in your terminal located in the folder you wish to install SockBot into.

npm install sockbot

Post Install Setup

If you installed via npm skip this step as npm has already installed all necessary dependencies.

Otherwise you will need to instruct npm to install the SockBot dependencies. From a terminal in the folder that SockBot was installed to execute the following command.

npm install

Once this command completes all dependencies of SockBot have been installed.

If you wish you may execute the unit tests for SockBot by executing the following command.

npm test

Configuration

Once installed SockBot will require a Configuration File to work properly. This is a JSON or YAML formatted file, the full details of which can be found in the configuration documentation.

Below is a sample configuration that sets the minimum core configuration and activates the echo module which replies to messages with the contents on the message received and is useful for testing.

---
core:
  username: someBotAccount
  password: someBotPassword
plugins:
  echo: true

Running the bot

Once a configuration file has been created it's time to start the bot! For this section we will assume that the configuration file is named config.yml and is placed in the same folder as SockBot proper.

A npm script has been created to run SockBot. In order to use this method execute the following command in the folder SockBot is installed to.

npm start config.yml

SockBot can also be started directly from the command line without using npm. To start SockBot this way execute the appropriate command below in the folder that SockBot is installed to.

For Node.js

node --harmony SockBot.js config.yml

For io.js

iojs --harmony_arrow_functions SockBot.js config.yml

Note: On some platforms e.g. Ubuntu, the node binary may installed as nodejs; this to avoid clashing with an older node package that existed in the repositories before Node.js was added.

At this point the bot should start and connect to Discourse. If all goes well SockBot should produce output similar to the example below.

accalia@sockdrawer:~/workspace/SockBot $ npm start config.yml

> sockbot@2.0.0 start /home/ubuntu/workspace/SockBot
> node --harmony --harmony_arrow_functions SockBot.js "config.yml"

[17:22:38] Command Registered: help: print command help listing
[17:22:38] Plugin `echo` Loaded
[17:22:39] SockBot `SockAdept` Started
[17:22:39] Polling Messages
[17:22:39] Polling Notifications
[17:22:42] Polling Messages

Proper function can be tested by sending a message to the bot account or by mentioning the bot account. SockBot should reply to such a summons by replying with the text of the post used to summon it.

Once function has been verified more complex behaviors can be enabled by crafting the appropriate configuration file that activates and configures the appropriate plugins.