Add documentation

.github/workflows/publish-docs.yaml

@@ -0,0 +1,64 @@
+name: Publish MeshChat Documentation
+on:
+  workflow_call:
+    inputs:
+      build_version:
+        required: true
+        type: string
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container:
+      image: jtackaberry/luadox:latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: release
+      - run: luadox -c luadox.conf
+      - name: Fix permissions
+        run: |
+          chmod -c -R +rX "_site/" | while read line; do
+            echo "::warning title=Invalid file permissions automatically fixed::$line"
+          done
+      - name: Update version strings
+        run: |
+          find docs -type f --exec sed -i "s/%VERSION%/${{ inputs.build_version }}/" {} \;
+        run: |
+          echo ::group::Archive artifact
+          tar -C "_site" \
+              -cvf "$RUNNER_TEMP/artifact.tar" \
+              --exclude=.git \
+              --exclude=.github \
+              .
+          echo ::endgroup::
+      - name: Upload artifact
+        id: upload-artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: github-pages
+          path: ${{ runner.temp }}/artifact.tar
+          retention-days: 1
+          if-no-files-found: error
+
+  # Deploy job
+  deploy:
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4 # or specific "vX.X.X" version tag for this action

.gitignore

@@ -0,0 +1 @@
+docs/.markupserve_index

README.md

@@ -1,5 +1,4 @@
-MeshChat
-========
+# MeshChat
 
 MeshChat for AREDN (in Lua). MeshChat has become the defacto standard
 chat application for AREDN networks. A number of features make it easy
@@ -10,49 +9,6 @@ to implement and use:
 * No account creation necessary--users access using call sign
 * Simple user interface
 
-History of MeshChat
--------------------
-
-This is the history of the various MeshChat versions that have existed--at
-least to the best of my knowledge.
-
-### MeshChat v0.4 - v1.02
-
-This was the original version of MeshChat written by Trevor Paskett (K7FPV)
-around 2015. It was written in Perl and worked well on the limited resources
-of the AREDN nodes. Around 2018 Trevor was not able to or not interested
-in supporting MeshChat any longer, it is unclear which but the project
-became stagnant at version v1.01 in August of 2018. There was a final
-release of v1.02 in September 2022 that mostly added a few patches and
-support for Debian Stretch.
-
-The K7FPV code base still exists at https://github.com/tpaskett/meshchat.
-
-In addition Trevor wrote a good amount of documentation for his versions
-which is still pretty well covers the current versions of MeshChat.
-The documentation can be found over at his blog, https://github.com/tpaskett/meshchat.
-
-### MeshChat v2.0 - v2.8
-
-When AREDN firmware v3.22.6.0 was released in June 2022, the AREDN development
-team stopped including Perl in the distribution in favor of LUA. In preparation
-of this change Tim Wilkinson (KN6PLV) started rewriting MeshChat in LUA
-March 2022 with the first release of the new code base in April 2022. The
-new MeshChat code continued to receive bug fixes for a year. At which
-time Tim's involvement on the AREDN development team prevented him from
-continuing to maintain MeshChat.
-
-### Future of MeshChat
-
-That brings the story upto the current time, September 2023, where I,
-Gerard Hickey (WT0F), have started to be the maintainer of the MeshChat
-code base. There has already been work to restructure the repository to
-make working with the code more effective and to automatically build
-packages when a release occurs.
-
-There are a number of bug fixes and incremental improvements that will be
-released in v2.9.
-
 If you are looking for a feature to be implemented or find a bug, please
 be sure to [create an issue](https://github.com/hickey/meshchat/issues/new)
 in the project so that it can be prioritized.

docs/History.md

@@ -0,0 +1,38 @@
+# History of MeshChat
+
+This is the history of the various MeshChat versions that have existed--at
+least to the best of my knowledge.
+
+## MeshChat v0.4 - v1.02
+
+This was the original version of MeshChat written by Trevor Paskett (K7FPV)
+around 2015. It was written in Perl and worked well on the limited resources
+of the AREDN nodes. Around 2018 Trevor was not able to or not interested
+in supporting MeshChat any longer, it is unclear which but the project
+became stagnant at version v1.01 in August of 2018. There was a final
+release of v1.02 in September 2022 that mostly added a few patches and
+support for Debian Stretch.
+
+The K7FPV code base still exists at https://github.com/tpaskett/meshchat.
+
+In addition Trevor wrote a good amount of documentation for his versions
+which is still pretty well covers the current versions of MeshChat.
+The documentation can be found over at his blog, https://github.com/tpaskett/meshchat.
+
+## MeshChat v2.0 - v2.10
+
+When AREDN firmware v3.22.6.0 was released in June 2022, the AREDN development
+team stopped including Perl in the distribution in favor of LUA. In preparation
+of this change Tim Wilkinson (KN6PLV) started rewriting MeshChat in LUA
+March 2022 with the first release of the new code base in April 2022. The
+new MeshChat code continued to receive bug fixes for a year. At which
+time Tim's involvement on the AREDN development team prevented him from
+continuing to maintain MeshChat.
+
+## Future of MeshChat
+
+That brings the story upto the current time, September 2023, where I,
+Gerard Hickey (WT0F), have started to be the maintainer of the MeshChat
+code base. There has already been work to restructure the repository to
+make working with the code more effective and to automatically build
+packages when a release occurs.

docs/Install.md

@@ -0,0 +1,22 @@
+# Installing MeshChat
+
+MeshChat is distributed as an Itsy package (IPK file) to be installed on an
+AREDN node. This is the simplest way to install MeshChat.
+
+Simply download the MeshChat package to your compute and then access the
+Administration panel in the AREDN's node setup. Under Package Management
+you will have the option to upload a package. Once uploaded the MeshChat
+system will be started within a couple of seconds.
+
+Usually there is not really any configuration that needs to be done, but
+review of the [configuration settings](../module/meshchatconfig.html) is
+suggested. To make any configuration changes one needs to log into the
+node using SSH and edit the file `/www/cgi-bin/meshchatconfig.lua`.
+
+## Installing MeshChat on Linux
+
+The current distribution of MeshChat does not currently support Linux. In
+order to run MeshChat on a Linux machine, one needs to download MeshChat
+v1.0.2 and install it on the Linux machine. Once installed, the configuration
+need to be updated to set the `api_host` setting to the hostname or IP
+of an AREDN node that has the MeshChat API package installed.

docs/Troubleshooting.md

@@ -0,0 +1,57 @@
+# Troubleshooting
+
+This is a "living" document. It is attempted to keep it up to date with
+any new problems and troubleshooting techniques. If you find something
+missing, please create an [Issue](https://github.com/hickey/meshchat/issues/new/choose)
+do describe what problem or issue is missing. Better yet is to fork the
+MeshChat repository, update the documentation in the forked repository
+and then generate a PR back to the official MeshChat repository. Your
+efforts will be greatly appreciated.
+
+It is important to realize that MeshChat is effectively two separate
+programs: one that runs in your browser (the frontend code) and one that
+runs on the AREDN node (the backend code or API). While it may not be
+obvious which piece of code is having the problem, it generally can be
+broken down as if there is an issue with the format of a message or it
+being displayed in the browser then the frontend code should be investigated.
+Otherwise the API should be investigated.
+
+## Installation Issues
+
+There is a known issue that if an older AREDN firmware is being upgraded,
+any additional packages will need to be reinstalled after the node has
+completed the firmware upgrade. This should not be the case for AREDN
+firmware 3.23.8.0 or greater.
+
+If it appears that the installation of the package did not completely
+install or is not fully functional, check the node to determine how much
+disk space is available. Generally one should plan on a minimum of 100 KB
+of disk space for MeshChat to operate.
+
+Package installation failures also generally have an error message displayed
+above the upload button when there is a failure. This can help indicate
+what the failure type was, so it should be reported back as a project
+issue using the link above.
+
+## Message Synchronization Issues
+
+In order for messages to be synchronized between MeshChat instances, the
+`meshchatsync` process needs to be running. Log into the node and execute
+`ps | grep meshchatsync` to see if the process exists. If it is not
+running, then one can start it with executing `/usr/local/bin/meshchatsync`.
+Doing so will keep the process attached to the current terminal and any
+error output will be displayed in the terminal. Once the terminal is
+exited, the `meshchatsync` process will terminate. So after determining
+that there are no errors being generated, it is best to reboot the node.
+This will allow `meshchatsync` to startup normally with no manual
+intervention.
+
+If it appears that `meshchatsync` is operating correctly, then the next
+item to check is that the message database exists and messages are being
+written to it. On an AREDN node, the message database is normally located
+in `/tmp/meshchat`. Check for a `messages.<ZONE NAME>`. If the message
+database does exist, post a new message in the MeshChat instance on the
+node and insure that the message gets written to the message database.
+
+Also insure that the message database has write permissions on the file.
+

luadox.conf

@@ -0,0 +1,29 @@
+[project]
+# Project name that is displayed on the top bar of each page
+name = MeshChat
+# HTML title that is appended to every page. If not defined, name is used.
+title = MeshChat (master)
+# A list of files or directories for LuaDox to parse.  Globs are supported.
+# This can be spread across multiple lines if you want, as long as the
+# other lines are indented.
+files = meshchat*
+#files = /data/src/data/www/cgi-bin/meshchat.lua /data/src/data/www/cgi-bin/meshchatlib.lua
+# The directory containing the rendered output files, which will be created
+# if necessary.
+outdir = _site
+# Path to a custom css file that will be included on every page.  This will
+# be copied into the outdir.
+# css = custom.css
+# Path to a custom favicon. This will be copied into the outdir.
+# favicon = img/favicon.png
+# If require()d files discovered in source should also be parsed.
+follow = false
+# Character encoding for input files, which defaults to the current system
+# locale.  Output files are always utf8.
+encoding = utf8
+
+[manual]
+index = README.md
+history = docs/History.md
+install = docs/Install.md
+troubleshoot = docs/Troubleshooting.md