From: plugd <plugd@thelambdalab.xyz>
Date: Sun, 11 Aug 2024 14:27:04 +0000 (+0200)
Subject: Added README.
X-Git-Url: https://thelambdalab.xyz/gitweb/index.cgi?a=commitdiff_plain;h=b2af18b746a9118b51dc6b50cac580945fe720f4;p=qwikboard.git

Added README.
---

diff --git a/README b/README
new file mode 100644
index 0000000..3d3d083
--- /dev/null
+++ b/README
@@ -0,0 +1,119 @@
+QWiKBoard
+=========
+
+QWikBoard is a simple Lua programme which provides the backend for a
+message board system based entirely around the QWK offline mail packet
+format.  The idea is to provide something akin to the message board
+elements of a 1980s-style BBS, but without the online elements.
+
+Requirements
+------------
+
+The programme itself has fairly modest requirements, needing only
+a Lua 5.4 interpreter and the lua-posix package. Under Debian systems
+these can be met by installing the required packages using apt:
+
+      apt-get install lua5.4 lua-posix
+
+Installation
+------------
+
+Installation simply involves placing the qwikboard executable Lua script
+somewhere in your execution path, for instance in /usr/local/bin.
+
+Setting up a message board
+--------------------------
+
+Each message board requires a directory on your filesystem to call its own.
+For a system-wide message board, a directory under /var is perhaps appropriate.
+(In this case, it probably makes sense to create a system user and group to
+own the directory.)
+
+For the purposes of this introduction, lets assume you've chosen the directory
+to be /var/mybbs.
+
+Once you've set up this directory, run qwikboard to create a default
+configuration file.
+
+    qwikboard /var/mybbs newcfg
+
+This will create a new file /var/mybbs/config.lua.  Open this file and modify
+to your liking.
+
+Finally, issue the following command to initialise the board structure.
+
+    qwikboard /var/mybbs init
+
+This command creates the board directory structure, including
+- /var/mybbs/conferences which holds the message database, and
+- /var/mybbs/notices which holds the notice files which are
+displayed to users by their offline mail reader when they open (hello)
+and close (goodbye) mail packets.  An additional file (news) contains
+any board-wide news you'd like to distribute to your users.
+
+Interacting with a message board
+--------------------------------
+
+Interaction with the board is of course primarily via QWK packets and
+corresponding REP files (reply files generated by offline mail readers).
+
+To generate a QWK file for board user USER, use the following
+
+   qwikboard /var/mybbs qwkout USER outfile.qwk
+
+The "outfile.qwk" argument specifies the name and location of the QWK file
+which will be generated.
+
+To incorporate new messages from user USER into the board, use the command
+
+   qwikboard /var/mybbs repin USER infile.rep
+
+(All messages will be sent from USER, regardless of the sender named in the
+rep file messages.) The "infile.rep" argument is the name and location of the
+REP file to be read.
+
+NNCP integration
+----------------
+
+Of course, manual generation of QWK files and reading of REP files
+using the above commands for each user would be incredibly tedious.
+QWiKBoard is intended to be used in conjunction with the NNCP store
+and forward networking tool, and provides the "nncp_handler" command
+for interaction with this system.
+
+To enable this, simply add an exec entry to any of your neighbours
+(entries in the "neigh" section of nncp.hjson) who you'd like to have
+access to the board.  For instance, for our board in /var/mybbs
+we could use:
+
+    exec: {
+        qwikboard: ["/usr/local/bin/qwikboard /var/mybbs nncp_handler"]
+    }
+
+Any of these neighbours can then retrieve QWK files using:
+
+    echo get | nncp-exec bbsnode qwikboard
+
+This will result in the QWK file being assembled sent to the
+requesting node using nncp-file, meaning the requesting node will also
+need an incoming directory specified.
+
+Similarly, REP files can be submitted using:
+
+   nncp-exec bbsnode qwikboard < replyfile.rep
+
+This will result in the messages contained in replyfile.rep being
+incorporated into the message database.
+
+The nncp_handler command assumes that the name of the sending NNCP
+node is the name of the user.  Thus, when registering users to the
+BBS, ensure that you configure their node names appropriately in
+nncp.hjson.
+
+License
+-------
+
+QWiKBoard is free software, and is distributed under the terms of the
+GNU General Public License version 3.0.  A copy of this license can be
+found in a file named COPYING in the same directory as this README
+file.
\ No newline at end of file