enigma-bbs/docs/index.md

4.6 KiB
Raw Blame History

Introduction

ENiGMA½ is a modern from scratch BBS package written in Node.js.

Quickstart

Unless you have a compelling reason to do otherwise, please use The Easy Way below.

The Easy Way

Under most Linux/UNIX like environments (Linux, BSD, OS X, ...) new users can simply execute the install.sh script to get everything up and running. Simply cut + paste the following into your terminal:

curl -o- https://raw.githubusercontent.com/NuSkooler/enigma-bbs/master/misc/install.sh | bash

For other environments such as Windows, see The Manual Way below.

The Manual Way (aka Advanced)

For Windows environments or if you simply like to do things manually, read on...

Prerequisites

  • Node.js version v6.x or higher
    • It is highly suggested to use nvm to manage your Node/io.js installs
  • Python 2.7.x
  • A compiler such as Clang or GCC for Linux/UNIX systems or a recent copy of Visual Studio (Visual Studio Express editions OK) for Windows users. Note that you should only need the Visual C++ component.

New to Node

If you're new to Node.js and/or do not care about Node itself and just want to get ENiGMA½ running these steps should get you going on most *nix type environments (Please consider the install.sh approach unless you really want to manually install!):

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.0/install.sh | bash
nvm install 6
nvm use 6

If the above completed without errors, you should now have nvm, node, and npm installed and in your environment.

For Windows nvm-like systems exist (nvm-windows, ...) or just download the installer.

Clone

git clone https://github.com/NuSkooler/enigma-bbs.git

Install Node Modules

cd enigma-bbs
npm install

Generate a SSH Private Key

To utilize the SSH server, a SSH Private Key will need generated. This step can be skipped if you do not wish to enable SSH access.

openssl genrsa -des3 -out ./misc/ssh_private_key.pem 2048

Create a Minimal Config

The main system configuration is handled via ~/.config/enigma-bbs/config.hjson. This is a HJSON file (compiliant JSON is also OK). See Configuration for more information.

Via oputil.js

oputil.js can be utilized to generate your initial configuration. This is the recommended way for all new users:

./oputil.js config new

(You will be asked a series of basic questions)

Example Starting Configuration

Below is an example configuration. It is recommended that you at least start with a generated configuration using oputil.js described above.

{
	general: {
		boardName: Super Awesome BBS
	}

	loginServers: {
		ssh: {
	    	privateKeyPass: YOUR_PK_PASS
	    	enabled: true /* set to false to disable the SSH server */
	    }
	}

	messageConferences: {
		local_general: {
			name: Local
			desc: Local Discussions
			default: true

		    areas: {
		    	local_music: {
					name: Music Discussion
					desc: Music, bands, etc.
					default: true
	        	}
	        }
	    }
	}
}

Launch!

./main.js

Monitoring Logs

Logs are produced by Bunyan which outputs each entry as a JSON object. To tail logs in a colorized and pretty pretty format, issue the following command:

tail -F /path/to/enigma-bbs/logs/enigma-bbs.log | /path/to/enigma-bbs/node_modules/bunyan/bin/bunyan

ENiGMA½ does not produce much to standard out. See below for tailing the log file to see what's going on.

Points of Interest

  • Default ports are 8888 (Telnet) and 8889 (SSH)
    • Note that on *nix systems port such as telnet/23 are privileged (e.g. require root). See this SO article for some tips on using these ports on your system if desired.
  • The first user you create via applying is the SysOp (aka root)
  • You may want to tail the logfile with Bunyan. See Monitoring Logs above.

Advanced Installation

If you've become convinced you would like a "production" BBS running ENiGMA½ a more advanced installation may be in order.

PM2 is an excellent choice for managing your running ENiGMA½ instances. Additionally, it is suggested that you run as a specific more locked down user (e.g. 'enigma').