-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* add API docs as comments * add luadox configuation * add parameter table to API calls * create documentation to be published * add github pages artifact code * remove unused README * make publish-docs workflow reusable for releases * add troubleshooting documentation --------- Signed-off-by: Gerard Hickey <hickey@kinetic-compute.com>
- Loading branch information
Showing
10 changed files
with
480 additions
and
50 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
docs/.markupserve_index |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
Oops, something went wrong.