Installation

SockBot is written entirely in JavaScript using ES6 syntax. As such it is compatible with Node.js >= 4.0. 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 Node.js with working npm to function.

Required software:

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.

It is recommended to install sockbot globally via NPM if you have sufficient access. This will put the sockbot binary in your path for conveniant access.

npm install -g 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
  owner: yourUsername
plugins:
  echo: true

Running the bot

For Production installs

For production installs where sockbot was installed globally execute the sockbot binary and provide the path to a configuration file

For example:

$ sockbot config.yml

For Dev installs

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.

node lib/app 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 your forum. If all goes well SockBot should produce output similar to the example below.

accalia_de_elementia@sockdrawer:~/workspace $ sockbot config.yml
[2016-04-03T17:18:08.528Z] Starting Sockbot 3.0.0 - Alpha Alpaca
[2016-04-03T17:18:08.545Z] Loaded configuration file: config.yml
[2016-04-03T17:18:08.545Z] Activating logon: sockbot
[2016-04-03T17:18:08.883Z] Using provider nodebb for sockbot
[2016-04-03T17:18:08.886Z] Loading plugin echo for sockbot
[2016-04-03T17:18:08.887Z] sockbot ready for login
[2016-04-03T17:18:10.955Z] sockbot login successful
[2016-04-03T17:18:11.335Z] Notifications Activated: Now listening for new notifications
[2016-04-03T17:18:11.335Z] sockbot activated

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.