Merge pull request #136 from davestephens/0.0.8-alpha

Documentation Updates
This commit is contained in:
Bryan Ashby 2017-10-29 12:14:23 -06:00 committed by GitHub
commit eddebd512b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 219 additions and 39 deletions

View File

@ -1,6 +1,6 @@
# ENiGMA½ BBS Software # 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! ENiGMA½ is a modern BBS software with a nostalgic flair!

View File

@ -1,7 +1,7 @@
# File Bases # 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: 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: 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 * [Gazelle](https://whatcd.github.io/Gazelle/) inspired system for searching & browsing files
* No File Conferences (just areas!) * No File Conferences (just areas!)

BIN
docs/images/vtxclient.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 128 KiB

View File

@ -24,7 +24,7 @@ For Windows environments or if you simply like to do things manually, read on...
### New to Node ### 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 ```bash
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.0/install.sh | 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 ./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 #### 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**. Below is an _example_ configuration. It is recommended that you at least **start with a generated configuration using oputil.js described above**.

View File

@ -100,9 +100,74 @@ A node entry starts with a FTN style address (up to 5D) **as a key** in `config.
#### TIC Support #### TIC Support
ENiGMA½ supports TIC files. This is handled by mapping TIC areas to local file areas. 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 #### 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. 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.

View File

@ -3,39 +3,32 @@
ENiGMA½ can run under your Linux / RPi installation! The following instructions should help get you started. ENiGMA½ can run under your Linux / RPi installation! The following instructions should help get you started.
## Tested RPi Models ## 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. 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 ### 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!

87
docs/vtx_web_client.md Normal file
View File

@ -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")

View File

@ -1,8 +1,10 @@
# Web Server # 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 ## 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 ```hjson
contentServers: { contentServers: {
@ -16,7 +18,12 @@ 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 ```hjson
contentServers: { contentServers: {
web: { web: {
@ -37,4 +44,5 @@ contentServers: {
Static files live relative to the `contentServers::web::staticRoot` path which defaults to `enigma-bbs/www`. Static files live relative to the `contentServers::web::staticRoot` path which defaults to `enigma-bbs/www`.
### Custom Error Pages ### 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`.

27
misc/vtx/vtx.html Normal file
View File

@ -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>