From 78b78e8c79e6d5a174c95c90d89b0cac88ca7a4f Mon Sep 17 00:00:00 2001 From: Bryan Ashby Date: Sat, 30 May 2020 22:39:27 -0600 Subject: [PATCH] Doc updates --- core/oputil/oputil_user.js | 4 ++- docs/_includes/nav.md | 1 + docs/admin/administration.md | 43 +++++++++++++++++++++++++ docs/admin/updating.md | 30 +++++++++++------ docs/troubleshooting/monitoring-logs.md | 6 ++-- 5 files changed, 70 insertions(+), 14 deletions(-) create mode 100644 docs/admin/administration.md diff --git a/core/oputil/oputil_user.js b/core/oputil/oputil_user.js index 376ee166..07f9227a 100644 --- a/core/oputil/oputil_user.js +++ b/core/oputil/oputil_user.js @@ -462,7 +462,9 @@ function twoFactorAuthOTP(user) { function listUsers() { // oputil user list [disabled|inactive|active|locked|all] - // :TODO: --after TIMESTAMP (new users) + // :TODO: --created-since SPEC and --last-called SPEC + // --created-since SPEC + // SPEC can be TIMESTAMP or e.g. "-1hour" or "-90days" // :TODO: --sort name|id let listWhat; if (argv._.length > 2) { diff --git a/docs/_includes/nav.md b/docs/_includes/nav.md index c4303fac..6b335617 100644 --- a/docs/_includes/nav.md +++ b/docs/_includes/nav.md @@ -89,6 +89,7 @@ - [Auto Signature Editor]({{ site.baseurl }}{% link modding/autosig-edit.md %}) - Administration + - [Administration]({{ site.baseurl }}{% link admin/administration.md %}) - [oputil]({{ site.baseurl }}{% link admin/oputil.md %}) - [Updating]({{ site.baseurl }}{% link admin/updating.md %}) diff --git a/docs/admin/administration.md b/docs/admin/administration.md new file mode 100644 index 00000000..8d15fba5 --- /dev/null +++ b/docs/admin/administration.md @@ -0,0 +1,43 @@ +--- +layout: page +title: Administration +--- + +# Administration + +## Keeping Up to Date +See [Updating](updating.md). + +## Viewing Logs +See [Monitoring Logs](/docs/troubleshooting/monitoring-logs.md). + +## Managing Users +User management is currently handled via the [oputil CLI](oputil.md). + +## Backing Up Your System +It is *highly* recommended to perform **regular backups** of your system. Nothing is worse than spending a lot of time setting up a system only to have to go away unexpectedly! + +In general, simply creating a copy/archive of your system is enough for the default configuration. If you have changed default paths to point outside of your main ENiGMA½ installation take special care to ensure these are preserved as well. Database files may be in a state of flux when simply copying files. See **Database Backups** below for details on consistent backups. + +### Database Backups +[SQLite's CLI backup command](https://sqlite.org/cli.html#special_commands_to_sqlite3_dot_commands_) can be used for creating database backup files. This can be performed as an additional step to a full backup to ensure the database is backed up in a consistent state (whereas simply copying the files does not make any guarantees). + +As an example, consider the following Bash script that creates foo.sqlite3.backup files: + +```bash +for dbfile in /path/to/enigma-bbs/db/*.sqlite3; do + sqlite3 $dbfile ".backup '/path/to/db_backup/$(basename $dbfile).backup'" +done +``` + +### Backup Tools +There are many backup solutions available across all platforms. Configuration of such tools is outside the scope of this documentation. With that said, the author has had great success with [Borg](https://www.borgbackup.org/). + +## General Maintenance Tasks +### Vacuuming Database Files +SQLite database files become less performant over time and waste space. It is recommended to periodically vacuum your databases. Before proceeding, you should make a backup! + +Example: +```bash +sqlite3 ./db/message.sqlite3 "vacuum;" +``` \ No newline at end of file diff --git a/docs/admin/updating.md b/docs/admin/updating.md index 8fda4692..3cf93768 100644 --- a/docs/admin/updating.md +++ b/docs/admin/updating.md @@ -2,20 +2,30 @@ layout: page title: Updating --- -## Updating your Installation -Updating ENiGMA½ can be a bit of a learning curve compared to other systems. Especially when running from Git cloned source, you'll want frequent updates. +# Updating +Keeping your system up to date ensures you have the latest fixes, features, and general improvements. Updating ENiGMA½ can be a bit of a learning curve compared to traditional binary-release systems you may be used to, especially when running from Git cloned source. -## Steps -In _general_ the steps are as follows: -1. `cd /path/to/enigma-bbs` -2. `git pull` -3. `npm update` or `yarn` to refresh any new or updated modules. -4. Merge updates to `config/menu_template.hjson` to your `config/yourbbsname-menu.hjson` file (or simply use the template as a reference to spot any newly added default menus that you may wish to have on your system as well!). +## Updating From Source +If you have installed using Git source (if you used the `install.sh` script) follow these general steps to update your system: + +1. **Back up your system**! +2. Pull down the latest source: +```bash +cd /path/to/enigma-bbs +git pull +``` +3. :bulb: Review `WHATSNEW.md` and `UPDATE.md` for any specific instructions or changes to be aware of. +4. Update your dependencies: +```bash +npm install # or 'yarn' +``` +4. Merge updates from `config/menu_template.hjson` to your `config/yourbbsname-menu.hjson` file (or simply use the template as a reference to spot any newly added default menus that you may wish to have on your system as well!). 5. If there are updates to the `art/themes/luciano_blocktronics/theme.hjson` file and you have a custom theme, you may want to look at them as well. - -:information_source: Always keep an eye on [WHATSNEW](/WHATSNEW.md) and [UPGRADE](/UPGRADE.md)! +6. Finally, restart your running ENiGMA½ instance. :information_source: Visual diff tools such as [DiffMerge](https://www.sourcegear.com/diffmerge/downloads.php) (free, works on all major platforms) can be very helpful for the tasks outlined above! +:information_source: It is recommended to tail the logs and poke around a bit after an update. + diff --git a/docs/troubleshooting/monitoring-logs.md b/docs/troubleshooting/monitoring-logs.md index 28a3773a..4fa27a5c 100644 --- a/docs/troubleshooting/monitoring-logs.md +++ b/docs/troubleshooting/monitoring-logs.md @@ -3,7 +3,7 @@ layout: page title: Monitoring Logs --- ## Monitoring Logs -ENiGMA½ does not produce much to stdout. Logs are produced by Bunyan which outputs each entry as a JSON object. +ENiGMA½ does not produce much to stdout. Logs are produced by [Bunyan](https://github.com/trentm/node-bunyan) which outputs each entry as a JSON object. Start by installing bunyan and making it available on your path: @@ -11,11 +11,11 @@ Start by installing bunyan and making it available on your path: npm install bunyan -g ``` -or with Yarn: +or via Yarn: ```bash yarn global add bunyan ``` - + To tail logs in a colorized and pretty format, issue the following command: ```bash tail -F /path/to/enigma-bbs/logs/enigma-bbs.log | bunyan