Merge pull request #136 from davestephens/0.0.8-alpha

Documentation Updates

README.md

@@ -1,6 +1,6 @@
 # ENiGMA½ BBS Software
 
-![alt text](docs/images/enigma-bbs.png "ENiGMA½ BBS")
+![ENiGMA½ BBS](docs/images/enigma-bbs.png "ENiGMA½ BBS")
 
 ENiGMA½ is a modern BBS software with a nostalgic flair!
 

docs/file_base.md

@@ -1,7 +1,7 @@
 # File Bases
 Starting with version 0.0.4-alpha, ENiGMA½ has support for File Bases! Documentation below covers setup of file area(s), but first some information on what to expect:
 
-## A Different Appoach
+## A Different Approach
 ENiGMA½ has strayed away from the old familure setup here and instead takes a more modern approach:
 * [Gazelle](https://whatcd.github.io/Gazelle/) inspired system for searching & browsing files
 * No File Conferences (just areas!)

docs/index.md

@@ -24,7 +24,7 @@ For Windows environments or if you simply like to do things manually, read on...
   
  
 ### 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 enviornments (Please consider the `install.sh` approach unless you really want to manually install!):
+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!):
 
 ```bash
 curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.0/install.sh | bash
@@ -64,7 +64,7 @@ The main system configuration is handled via `~/.config/enigma-bbs/config.hjson`
 ./oputil.js config new
 ```
 
-(You wil be asked a series of basic questions)
+(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**.

docs/msg_networks.md

@@ -100,9 +100,74 @@ A node entry starts with a FTN style address (up to 5D) **as a key** in `config.
 #### TIC Support
 ENiGMA½ supports TIC files. This is handled by mapping TIC areas to local file areas.
 
-Under a given node (described above) TIC configuration may be supplied.
+Under a given node (like the one configured above), TIC configuration may be supplied:
+
+```hjson
+{
+  scannerTossers: {
+    ftn_bso: {
+      nodes: {
+        "46:*": {
+          packetType: 2+
+          packetPassword: mypass
+          encoding: cp437
+          archiveType: zip
+          tic: {
+            password: TESTY-TEST
+            uploadBy: Agoranet TIC
+            allowReplace: true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+You then need to configure the mapping between TIC areas you want to carry, and the file 
+base area for them to be tossed to. Start by creating a storage tag and file base, if you haven't 
+already:
+
+````hjson
+fileBase: {
+    areaStoragePrefix: /home/bbs/file_areas/
+    
+    storageTags: {
+        msg_network: "msg_network"
+    }
+    
+    areas: {
+        msgNetworks: {
+            name: Message Networks
+            desc: Message networks news & info
+            storageTags: [
+                "msg_network"
+            ]
+        }
+    }
+}
+
+````
+and then create the mapping between the TIC area and the file area created:
+
+````hjson
+ticAreas: {
+    agn_node: {
+        areaTag: msgNetworks
+        hashTags: agoranet,nodelist
+        storageTag: msg_network
+    }
+    
+    agn_info: {
+        areaTag: msgNetworks
+        hashTags: agoranet,infopack
+        storageTag: msg_network
+    }
+}
+
+````
+Multiple TIC areas can be mapped to a single file base area. 
 
-TODO
 
 #### Scheduling
 Schedules can be defined for importing and exporting via `import` and `export` under `schedule`. Each entry is allowed a "free form" text and/or special indicators for immediate export or watch file triggers.

docs/rpi.md

@@ -3,39 +3,32 @@
 ENiGMA½ can run under your Linux / RPi installation! The following instructions should help get you started.
 
 ## Tested RPi Models
-###Model A
+### Model A
-Works, but fairly slow (Node itself is not the fastest on this device). May work better overlocked, etc.
+Works, but fairly slow when browsing message areas (Node itself is not the fastest on this device). May work better overlocked, etc.
 
-###v2 Model B
+### v2 Model B
-Works well with default rasbian, follow the normal quickstart install procedure, except for installing nodejs. To install nodejs do the following: 
+Works well with Raspbian!
-    
-    curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
-    sudo apt-get install -y nodejs
 
 Keep in mind, compiling the dependencies with `npm install` will take some time and appear to hang. Just be patient.
 
-##Example Configuration: RPi Model A + Minibian
+## Example Configuration: RPi Model A + Raspbian Stretch Lite
 
 ### Basic Instructions
 
-1. Download and `dd` the Minibian .img file from https://minibianpi.wordpress.com/ to a SDCARD. Cards >= 16GB recommended.
-2. After booting Minibian, expand your file system. See http://elinux.org/RPi_Resize_Flash_Partitions#Manually_resizing_the_SD_card_on_Raspberry_Pi for information.
-3. Update & upgrade: `apt-get update && apt-get upgrade`
-4. It is recommended that you install `sudo` and create an admin user: `apt-get install sudo`, `adduser <yourname>`, `adduser <yourname> sudo` (reboot & login as the user your just created)
-5. We want to build dependencies with a updated version of GCC. The following works to install GCC 4.9 on Minibian "wheezy":
-a. Update */etc/apt/sources.list* replacing all "wheezy" with "jessie"
-b. `sudo apt-get update`
-c. `sudo apt-get install gcc-4.9 g++-4.9`
-d. Update */etc/apt/sources.list* reverting all "jessie" back to "wheezy"
-e. `sudo apt-get update`
-f. Update alternatives: `sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.9 60 --slave /usr/bin/g++ g++ /usr/bin/g++-4.9`
-6. Install dependencies: `sudo apt-get install make python libicu-dev libssl-dev git`
-7. Install the latest Node.js from here: http://node-arm.herokuapp.com/ (**only download the .dep and dpkg install it!**)
-8. The RPi A has very low memory, we'll need a swap file: 
-a. `sudo dd if=/dev/zero of=tmpswap bs=1024 count=1M`
-b. `sudo mkswap tmpswap`
-c. `sudo swapon tmpswap`
-9. Clone enigma-bbs.git
-10. Install dependencies. Here we will force GCC 4.9 for compilation: `CC=gcc-4.9 npm install`
-11. Follow generic setup for creating a config.hjson, etc. and you should be ready to go!
 
+1. Download [Raspbian Stretch Lite](https://www.raspberrypi.org/downloads/raspbian/). Follow the instructions
+on the [Raspbian site](https://www.raspberrypi.org/documentation/installation/installing-images/README.md) regarding how
+to get it written to an SD card.
+
+2. Run `sudo raspi-config`, then:
+    1. Set your timezone (option 4, option I2)
+    2. Enable SSH (option 5, option P2)
+    3. Expand the filesystem to use the entire SD card (option 7, option A1)
+
+3. Update & upgrade all packages: `apt-get update && apt-get upgrade`
+    
+4. Install required packages: `sudo apt install lrzsz p7zip-full`
+
+5. Follow the [Quickstart](docs/index.md) instructions to install ENiGMA½.
+
+6. Profit!

docs/vtx_web_client.md

@@ -0,0 +1,87 @@
+# VTX Web Client
+ENiGMA supports the VTX websocket client for connecting to your BBS from a web page. Example usage can be found at 
+[Xibalba](https://l33t.codes/vtx/xibalba.html) and [fORCE9](https://bbs.force9.org/vtx/force9.html).
+
+## Before You Start
+
+There are a few things out of scope of this document:
+
+ - You'll need a web server for hosting the files - this can be anywhere, but it obviously makes sense to host it 
+ somewhere with a hostname relevant to your BBS!
+
+ - It's not required, but you should use SSL certificates to secure your website, and for supplying to ENiGMA to 
+ secure the websocket connections. [Let's Encrypt](https://letsencrypt.org/) provide a free well-respected service.
+ 
+ - How you make the websocket service available on the internet is up to you, but it'll likely by forwarding ports on 
+ your router to the box hosting ENiGMA. Use the same method you did for forwarding the telnet port. 
+ 
+## Setup
+
+1. Enable the websocket in ENiGMA, by adding `webSocket` configuration to the `loginServers` block (create it if you
+don't already have it defined). 
+
+    ````hjson
+    loginServers: {
+            webSocket : {
+                    port: 8810
+                    enabled: true
+                    securePort: 8811
+                    certPem: /path/to/https_cert.pem
+                    keyPem: /path/to/https_cert_key.pem
+            }
+    }
+    ````
+
+2. Restart ENiGMA and check the logs to ensure the websocket service starts successfully, you'll see something like the 
+following:
+
+    ````
+    [2017-10-29T12:13:30.668Z]  INFO: ENiGMA½ BBS/30978 on force9: Listening for connections (server="WebSocket (insecure)", port=8810)
+    [2017-10-29T12:13:30.669Z]  INFO: ENiGMA½ BBS/30978 on force9: Listening for connections (server="WebSocket (secure)", port=8811)
+    ````
+                
+3. Download the [VTX_ClientServer](https://github.com/codewar65/VTX_ClientServer/archive/master.zip) to your
+webserver, and unpack it to a temporary directory. 
+
+4. Download the example [VTX client HTML file](/misc/vtx/vtx.html) and save it to your webserver root.
+
+5. Create an `assets/vtx` directory within your webserver root, so you have a structure like the following:
+
+    ````text
+    ├── assets
+    │   └── vtx
+    └── vtx.html
+    ````
+
+6. From the VTX_ClientServer package unpacked earlier, copy the contents of the `www` directory into `assets/vtx` directory.
+
+7. Create a vtxdata.js file, and save it to `assets/vtx`:
+
+    ````javascript
+    var vtxdata = {
+        sysName: "Your Awesome BBS",
+        wsConnect: "wss://your-hostname.here:8811" 
+        term: "ansi-bbs",
+        codePage: "CP437",
+        fontName: "UVGA16",
+        fontSize: "24px",
+        crtCols: 80,
+        crtRows: 25,
+        crtHistory: 500,
+        xScale: 1,
+        initStr: "",
+        defPageAttr: 0x1010,
+        defCrsrAttr: 0x0207,
+        defCellAttr: 0x0007,
+        telnet: 1,
+        autoConnect: 0
+    };
+    ````
+
+8. Update `sysName` and `wsConnect` accordingly. Use `wss://` if you set up the websocket service with SSL, `ws://` 
+otherwise.
+    
+9. If you navigate to http://your-hostname.here/vtx.html, you should see a splash screen like the following:
+    ![VTXClient](images/vtxclient.png "VTXClient")
+
+ 

docs/web_server.md

@@ -1,8 +1,10 @@
 # Web Server
-ENiGMA½ comes with a built in *content server* for supporting both HTTP and HTTPS. Currently the [File Bases](file_base.md) registers routes for file downloads, and static files can also be served for your BBS. Other features will likely come in the future or you can easily write your own!
+ENiGMA½ comes with a built in *content server* for supporting both HTTP and HTTPS. Currently the 
+[File Bases](file_base.md) registers routes for file downloads, and static files can also be served for your BBS. Other features will likely come in the future or you can easily write your own!
 
 ## Configuration
-By default the web server is not enabled. To enable it, you will need to at a minimum configure two keys in the `contentServers::web` section of `config.hjson`:
+By default the web server is not enabled. To enable it, you will need to at a minimum configure two keys in 
+the `contentServers::web` section of `config.hjson`:
 
 ```hjson
 contentServers: {
@@ -16,12 +18,17 @@ contentServers: {
 }
 ```
 
-This will configure HTTP for port 8080 (override with `port`). To additionally enable HTTPS, you will need a PEM encoded SSL certificate and private key. Once obtained, simply enable the HTTPS server:
+This will configure HTTP for port 8080 (override with `port`). To additionally enable HTTPS, you will need a 
+PEM encoded SSL certificate and private key. [LetsEncrypt](https://letsencrypt.org/) supply free trusted 
+certificates that work perfectly with ENiGMA½.
+
+Once obtained, simply enable the HTTPS server:
+
 ```hjson
 contentServers: {
 	web: {
 		domain: bbs.yourdomain.com
-		//	set 'overrideUrlPrefix' if for example, you use a transparent proxy in front of ENiGMA and need to be explicit about URLs the system hands out
+		// set 'overrideUrlPrefix' if for example, you use a transparent proxy in front of ENiGMA and need to be explicit about URLs the system hands out
 		overrideUrlPrefix: https://bbs.yourdomain.com
 		https: {
 			enabled: true
@@ -37,4 +44,5 @@ contentServers: {
 Static files live relative to the `contentServers::web::staticRoot` path which defaults to `enigma-bbs/www`. 
 
 ### Custom Error Pages
-Customized error pages can be created for [HTTP error codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error) by providing a `<error_code>.html` file in the *static routes* area. For example: `404.html`.
+Customized error pages can be created for [HTTP error codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error) 
+by providing a `<error_code>.html` file in the *static routes* area. For example: `404.html`.

misc/vtx/vtx.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <script type='text/javascript' src='https://cdn.jsdelivr.net/pako/1.0.3/pako.min.js'></script>
+    <script type='text/javascript' src='assets/vtx/vtxdata.js'></script>
+    <script type='text/javascript' src='assets/vtx/vtxclient.js'></script>
+    <style>
+        .bg {
+            background-color: #000
+        }
+        .vtxClient {
+            text-align: center;
+            margin: 0 auto;
+            display: inline-block;
+            padding: 32px;
+        }
+    </style>
+</head>
+<body class="bg">
+<div style="text-align:center">
+    <div id="vtxclient" class="vtxClient">
+        <!-- VTX client will appear in here -->
+    </div>
+</div>
+</body>
+</html>