Merge pull request #136 from davestephens/0.0.8-alpha
Documentation Updates
This commit is contained in:
commit
eddebd512b
|
@ -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!
|
||||||
|
|
||||||
|
|
|
@ -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!)
|
||||||
|
|
Binary file not shown.
After Width: | Height: | Size: 128 KiB |
|
@ -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**.
|
||||||
|
|
|
@ -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.
|
||||||
|
|
49
docs/rpi.md
49
docs/rpi.md
|
@ -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!
|
||||||
|
|
|
@ -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")
|
||||||
|
|
||||||
|
|
|
@ -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`.
|
||||||
|
|
|
@ -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>
|
Loading…
Reference in New Issue