crichardson/enigma-bbs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Automatically generate the navigation

Browse Source
This commit is contained in:
Nathan Byrd
2022-02-04 08:51:03 -06:00
parent 4793ad0492
commit b5b0cc3ac5
94 changed files with 236 additions and 335 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
docs/_docs/installation/docker.md Normal file
View File

@@ -0,0 +1,72 @@
---
layout: page
title: Docker
---
**You'll need Docker installed before going any further. How to do so are out of scope of these docs, but you can find full instructions
for every operating system on the [Docker website](https://docs.docker.com/engine/install/).**
## Quick Start
prepare a folder where you are going to save your bbs files.
- Generate some config for your BBS: \
you can perform this step from anywhere - but make sure to consistently run it from the same place to retain your config inside the docker guest
```
docker run -it -p 8888:8888 \
--name " ENiGMABBS" \
-v "$(pwd)/config:/enigma-bbs/config" \
-v "$(pwd)/db:/enigma-bbs/db" \
-v "$(pwd)/logs:/enigma-bbs/logs" \
-v "$(pwd)/filebase:/enigma-bbs/filebase" \
-v "$(pwd)/art:/enigma-bbs/art" \
-v "$(pwd)/mods:/enigma-bbs/mods" \
-v "$(pwd)/mail:/mail" \
enigmabbs/enigmabbs:latest
```
- Run it: \
you can use the same command as above, just daemonize and drop interactiveness (we needed it for config but most of the time docker will run in the background)
````
docker run -d -p 8888:8888 \
--name "ENiGMABBS" \
-v "$(pwd)/config:/enigma-bbs/config" \
-v "$(pwd)/db:/enigma-bbs/db" \
-v "$(pwd)/logs:/enigma-bbs/logs" \
-v "$(pwd)/filebase:/enigma-bbs/filebase" \
-v "$(pwd)/art:/enigma-bbs/art" \
-v "$(pwd)/mods:/enigma-bbs/mods" \
-v "$(pwd)/mail:/mail" \
enigmabbs/enigmabbs:latest
````
- Restarting and Making changes\
if you make any changes to your host config folder they will persist, and you can just restart ENiGMABBS container to load any changes you've made.
```docker restart ENiGMABBS```
:bulb: Configuration will be stored in `$(pwd)/enigma-bbs/config`.
:bulb: Windows users - you'll need to switch out `$(pwd)/enigma-bbs/config` for a Windows-style path.
## Volumes
Containers by their nature are ephermeral. Meaning, stuff you want to keep (config, database, mail) needs
to be stored outside of the running container. As such, the following volumes are mountable:
| Volume | Usage |
|:------------------------|:---------------------------------------------------------------------|
| /enigma-bbs/art | Art, themes, etc |
| /enigma-bbs/config | Config such as config.hjson, menu.hjson, prompt.hjson, SSL certs etc |
| /enigma-bbs/db | ENiGMA databases |
| /enigma-bbs/filebase | Filebase |
| /enigma-bbs/logs | Logs |
| /enigma-bbs/mods | ENiGMA mods |
| /mail | FTN mail (for use with an external mailer) |
## Building your own image
Customising the Docker image is easy!
1. Clone the ENiGMA-BBS source.
2. Build the image
```
docker build -f ./docker/Dockerfile .
```

20
docs/_docs/installation/install-script.md Normal file
View File

@@ -0,0 +1,20 @@
---
layout: page
title: Install Script
---
## Install Script
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. Cut + paste the following into your terminal:
```
curl -o- https://raw.githubusercontent.com/NuSkooler/enigma-bbs/master/misc/install.sh | bash
```
:eyes: You may wish to review the [installation script](https://raw.githubusercontent.com/NuSkooler/enigma-bbs/master/misc/install.sh)
on GitHub before running it!
The script will install `nvm`, Node.js and grab the latest ENiGMA BBS from GitHub. It will also guide you through creating a basic configuration file, and recommend some packages to install.
:information_source: After installing:
* Read [External Binaries](../configuration/external-binaries.md)
* Read [Updating](../admin/updating.md)

18
docs/_docs/installation/installation-methods.md Normal file
View File

@@ -0,0 +1,18 @@
---
layout: page
title: Installation Methods
---
## Installation Methods
There are multiple ways of installing ENiGMA BBS, depending on your level of experience and desire to do things manually versus have it automated for you.
| Method | Operating System Compatibility | Notes |
|--------|--------------------------------|-------|
| [Installation Script](install-script.md) | Linux, BSD, OSX | Quick and easy installation under most Linux/UNIX like environments (Linux, BSD, OS X, ...) |
| [Docker Images](docker.md) | Linux, BSD, OSX, Windows | Easy upgrades, compatible with all operating systems, no dependencies to install |
| [Manual](manual.md) | Linux, Windows, BSD (And others; YMMV!) | If you like doing things manually, or are running Windows |
## Community HOWTO's
:scroll: Check out [this awesome video on installation and basic configuration](https://youtu.be/WnN-ucVi3ZU) from Al's Geek Lab!
## Keeping Up To Date
After installing, you'll want to [keep your system updated](../admin/updating.md).

68
docs/_docs/installation/manual.md Normal file
View File

@@ -0,0 +1,68 @@
---
layout: page
title: Manual Installation
---
For Linux environments it's recommended you run the [install script](install-script.md). If you like to
do things manually, read on...
## Prerequisites
* [Node.js](https://nodejs.org/) version **v12.x LTS or higher** (Other versions may work but are not supported).
* :bulb: It is **highly** recommended to use [Node Version Manager (NVM)](https://github.com/creationix/nvm) to manage your Node.js installation if you're on a Linux/Unix environment.
* [Python](https://www.python.org/downloads/) for compiling Node.js packages with native extensions via `node-gyp`.
* A compiler such as Clang or GCC for Linux/UNIX systems or a recent copy of Visual Studio
([Visual Studio Express](https://www.visualstudio.com/en-us/products/visual-studio-express-vs.aspx) editions
are OK) for Windows users. Note that you **should only need the Visual C++ component**.
* [Git](https://git-scm.com/downloads) to check out the ENiGMA source code.
## Node.js
### With NVM
Node Version Manager (NVM) is an excellent way to install and manage Node.js versions on most UNIX-like environments. [Get the latest version here](https://github.com/creationix/nvm). The nvm install may look _something_ like this:
```bash
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash
```
:information_source: Do not cut+paste the above command! Visit the [NVM](https://github.com/creationix/nvm) page and run the latest version!
Next, install Node.js with NVM:
```bash
nvm install 12
nvm use 12
nvm alias default 12
```
If the above steps completed without errors, you should now have `nvm`, `node`, and `npm` installed and in your environment.
For Windows nvm-like systems exist ([nvm-windows](https://github.com/coreybutler/nvm-windows), ...) or [just download the installer](https://nodejs.org/en/download/).
## ENiGMA BBS
```bash
git clone https://github.com/NuSkooler/enigma-bbs.git
```
## Install Node Packages
```bash
cd enigma-bbs
npm install # yarn also works
```
## Other Recommended Packages
ENiGMA BBS makes use of a few packages for archive and legacy protocol support. They're not pre-requisites for running ENiGMA, but without them you'll miss certain functionality. Once installed, they should be made available on your systems `PATH`.
:information_source: Please see [External Binaries](../configuration/external-binaries.md) for information on setting these up.
:information_source: Additional information in [Archivers](../configuration/archivers.md) and [File Transfer Protocols](../configuration/file-transfer-protocols.md)
## Config Files
You'll need a basic configuration to get started. The main system configuration is handled via `config/config.hjson`. This is an [HJSON](http://hjson.org/) file (compliant JSON is also OK). See [Configuration](../configuration/) for more information.
Use `oputil.js` to generate your **initial** configuration:
```bash
./oputil.js config new
```
Follow the prompts!

13
docs/_docs/installation/network.md Normal file
View File

@@ -0,0 +1,13 @@
---
layout: page
title: Network Setup
---
## Hosting an ENIGMA instance from your Home Network
If you are hosting your ENGIMA instance from inside your local network, you'll need to open your chosen ports on your router, so people outside your local area network can access the BBS.
Each router has a different way of doing this, but this [comprehensive resource](https://portforward.com/) explains how to port forward on most common brand routers.
Secondly, it is likely that your public facing server IP is a [Dynamic Address](https://support.opendns.com/hc/en-us/articles/227987827-What-is-a-Dynamic-IP-Address-) automatically provisoned to you by your ISP. You can contact your ISP and request a static IP, but in some areas this isn't available to consumers, only businesses.
Using a tool like [Duck DNS](https://www.duckdns.org/) will give you a free subdomain that automatically adjusts its records whenever your IP Address changes.

14
docs/_docs/installation/os-hardware.md Normal file
View File

@@ -0,0 +1,14 @@
---
layout: page
title: OS & Hardware Specific Information
---
There are multiple ways of installing ENiGMA BBS, depending on your level of experience and desire to do things manually versus have it automated for you.
In general, please see [Installation Methods](installation-methods.md) and [Install Script](install-script.md).
Below are some special cases:
| Method | Notes |
|--------|-------|
| [Raspberry Pi](rpi.md) | All Raspberry Pi models work great with ENiGMA½! |
| [Windows](windows.md) | Compatible with all Windows Operating Systems |

12
docs/_docs/installation/production.md Normal file
View File

@@ -0,0 +1,12 @@
---
layout: page
title: Production Installation
---
If you've become convinced you would like a "production" BBS running ENiGMA½ a more advanced installation
may be in order.
[PM2](https://github.com/Unitech/pm2) is an excellent choice for managing your running ENiGMA½ instances if
you've installed via the [install script](install-script.md) or [manual installation](manual.md) method.
Additionally, it is suggested that you run as a specific more locked down user (e.g. 'enigma').
If you're running ENiGMA via Docker, then process management is already handled for you!

27
docs/_docs/installation/rpi.md Normal file
View File

@@ -0,0 +1,27 @@
---
layout: page
title: Raspberry Pi
---
All Raspberry Pi models work great with ENiGMA½! Keep in mind compiling the dependencies with
`npm install` will take some time and *may* appear to hang. It's still working - just be patient and let it
complete.
### Basic Instructions
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 [installation instructions](../installation/) to install ENiGMA½.
6. Profit!

49
docs/_docs/installation/testing.md Normal file
View File

@@ -0,0 +1,49 @@
---
layout: page
title: Testing Your Installation
---
Once you've completed your chosen installation method, it's time to test!
_Note that if you've used the [Docker](docker.md) installation method, you've already done this._
```bash
./main.js
```
If everything went OK:
```bash
ENiGMA½ Copyright (c) 2014-2021, Bryan Ashby
_____________________ _____ ____________________ __________\_ /
\__ ____/\_ ____ \ /____/ / _____ __ \ / ______/ // /___jp!
// __|___// | \// |// | \// | | \// \ /___ /_____
/____ _____| __________ ___|__| ____| \ / _____ \
---- \______\ -- |______\ ------ /______/ ---- |______\ - |______\ /__/ // ___/
/__ _\
<*> ENiGMA½ // HTTPS://GITHUB.COM/NUSKOOLER/ENIGMA-BBS <*> /__/
-------------------------------------------------------------------------------
System started!
```
Grab your favourite telnet client, connect to localhost:8888 and test out your installation.
To shut down the server, press Ctrl-C.
## Points of Interest
* The default port for Telnet is 8888 and 8889 for SSH.
* Note that on *nix systems port such as telnet/23 are privileged (e.g. require root). See
[this SO article](http://stackoverflow.com/questions/16573668/best-practices-when-running-node-js-with-port-80-ubuntu-linode) for some tips on using these ports on your system if desired.
* The first user you create when logging in will be automatically be added to the `sysops` group.
## Telnet Software
If you don't have any telnet software, these are compatible with ENiGMA½:
* [SyncTERM](http://syncterm.bbsdev.net/)
* [EtherTerm](https://github.com/M-griffin/EtherTerm)
* [NetRunner](http://mysticbbs.com/downloads.html)
* [MagiTerm](https://magickabbs.com/utils/)
* [VTX](https://github.com/codewar65/VTX_ClientServer) (Browser based)
* [fTelnet](https://www.ftelnet.ca/) (Browser based)

71
docs/_docs/installation/windows.md Normal file
View File

@@ -0,0 +1,71 @@
---
layout: page
title: Installation Under Windows
---
## Installation Under Windows
ENiGMA½ will run on both 32bit and 64bit Windows. If you want to run 16bit doors natively then you should use a 32bit Windows.
### Basic Instructions
1. Download and Install [Node.JS](https://nodejs.org/).
1. Upgrade NPM : At this time node comes with NPM 5.6 preinstalled. To upgrade to a newer version now or in the future on windows follow this method. `*Run PowerShell as Administrator`
`*Initial Install`
```Powershell
Set-ExecutionPolicy Unrestricted -Scope CurrentUser -Force
npm install -g npm-windows-upgrade
```
`*Upgrade`
```Powershell
npm-windows-upgrade
```
Note: Do not run `npm i -g npm`. Instead use `npm-windows-upgrade` to update npm going forward.
Also if you run the NodeJS installer, it will replace the node version.
2. Install [windows-build-tools for npm](https://www.npmjs.com/package/windows-build-tools)
`*This will also install python 2.7`
```Powershell
npm install --global --production windows-build-tools
```
2. Install [7zip](https://www.7-zip.org/download.html).
*Add 7zip to your path so `7z` can be called from the console
1. Right click `This PC` and Select `Properties`
2. Go to the `Advanced` Tab and click on `Environment Variables`
3. Select `Path` under `System Variables` and click `Edit`
4. Click `New` and paste the path to 7zip
5. Close your console window and reopen. You can type `7z` to make sure it's working.
(Please see [Archivers](../configuration/archivers.md) for additional archive utilities!)
3. Install [Git](https://git-scm.com/downloads) and optionally [TortoiseGit](https://tortoisegit.org/download/).
4. Clone ENiGMA½ - browse to the directory you want and run
```Powershell
git clone "https://github.com/NuSkooler/enigma-bbs.git"
```
Optionally use the TortoiseGit by right clicking the directory and selecting `Git Clone`.
5. Install ENiGMA½.
1. In the enigma directory run
```Powershell
npm install
```
2. Generate your initial configuration: `Follow the prompts!`
```Powershell
node .\oputil.js config new
```
3. Edit your configuration files in `enigma-bbs\config` with [Notepad++](https://notepad-plus-plus.org/download/) or [Visual Studio Code](https://code.visualstudio.com/Download)
4. Run ENiGMA½
```Powershell
node .\main.js
```
6. Look at [Production Installation](production.md) for maintaining ENiGMA½ when you are ready to go live.