Add troubleshooting instructions

editions/multiwikidocs/tiddlers/Database Engines.tid

@@ -0,0 +1,15 @@
+title: Database Engines
+tags: Reference
+
+MWS uses [[SQLite]] for data storage. It supports choosing between two "database engines" that are based on two different npm modules:
+
+* [[better-sqlite3|https://www.npmjs.com/package/better-sqlite3]] is written partially in C/C++ and so requires compilation for the target platform
+* [[node-sqlite3-wasm|https://www.npmjs.com/package/node-sqlite3-wasm]] is written entirely in JavaScript and does not require compilation, but does require a WebAssembly-capable Node.js host. This is not currently possible on some platforms such as iOS/iPadOS
+
+By default `npm install` will install both database engines. By default it will use `better-sqlite3`. To switch to using `node-sqlite3-wasm`, set the system configuration tiddler `$:/config/MultiWikiServer/Engine` to `wasm` (the default value is `better`). Note that this tiddler resides in the [[Administration Wiki]].
+
+!! Avoiding Installation Errors
+
+If you encounter errors during `npm install` related to `gyp` or `prebuild`, you may be able to avoid them by using `node-sqlite3-wasm` instead of `better-sqlite3`. However, it will be necessary to manually install `node-sqlite3-wasm` and its dependencies. This can be done by running the following commands in your terminal:
+
+<<.copy-code-to-clipboard "npm install node-sqlite3-wasm">>

editions/multiwikidocs/tiddlers/Installation using Git.tid

@@ -6,12 +6,14 @@ created: 20241105133737778
 These instructions require basic knowledge both of the terminal and of Git. There are also [[alternative instructions without using Git|Installation]].
 
 # Clone the code from GitHub with: <<.copy-code-to-clipboard "git clone -b multi-wiki-support --single-branch https://github.com/TiddlyWiki/TiddlyWiki5">>
-# Open a terminal window in the root of the downloaded folder
+# Open a terminal window and set the current directory to the root of the downloaded folder
 # Install the dependencies with the command: <<.copy-code-to-clipboard "npm install">>
 # Start the server with the command: <<.copy-code-to-clipboard "npm start">>
 # To use MWS, visit http://localhost:8080 in a browser on the same computer
 # When you have finished using MWS, stop the server with <kbd>ctrl-C</kbd>
 
+See [[Troubleshooting]] if you encounter any errors.
+
 To update your copy of MWS with newer changes from ~GitHub, run the following command:
 
 <<.copy-code-to-clipboard "git pull">>

editions/multiwikidocs/tiddlers/Installation.tid

@@ -6,10 +6,12 @@ created: 20241105133737778
 These instructions require minimal knowledge of the terminal. There are also [[alternative instructions for those using Git|Installation using Git]].
 
 # Download the code [[direct from GitHub|https://github.com/TiddlyWiki/TiddlyWiki5/archive/refs/pull/7915/head.zip]]
-# Open a terminal window in the root of the downloaded folder
+# Open a terminal window and set the current directory to the root of the downloaded folder
 # Install the dependencies with the command: <<.copy-code-to-clipboard "npm install">>
 # Start the server with the command: <<.copy-code-to-clipboard "npm start">>
 # To use MWS, visit http://localhost:8080 in a browser on the same computer
 # When you have finished using MWS, stop the server with <kbd>ctrl-C</kbd>
 
-To update your copy of MWS with newer changes will require re-downloading the code, taking care not to lose any changes you might have made.
+See [[Troubleshooting]] if you encounter any errors.
+
+To update your copy of MWS in the future with newer changes will require re-downloading the code, taking care not to lose any changes you might have made.

editions/multiwikidocs/tiddlers/Troubleshooting gyp-prebuild Installation Errors.tid

@@ -0,0 +1,19 @@
+title: Troublesheeting gyp/prebuild Installation Errors
+tags: Troubleshooting
+modified: 20241105133737778
+created: 20241105133737778
+
+Installation may fail with errors related to `gyp` or `prebuild`. These errors are caused by missing dependencies or incorrect versions of dependencies.
+
+Note that in most cases, these errors occur because of the use of the npm module [[better-sqlite3|https://www.npmjs.com/package/better-sqlite3]]. This module is mostly written in C, and thus requires compilation for the target platform. MWS supports switchable database engines, and also supports the use of the [[node-sqlite3-wasm|https://www.npmjs.com/package/node-sqlite3-wasm]] module which is written in ~JavaScript and does not require compilation and so may avoid these errors. See [[Database Engines]] for more details of how to switch between engines.
+
+The following steps may help resolve errors involving `gyp` or `prebuild`:
+
+# Ensure that you have the latest version of Node.js installed. You can download the latest version from the [[Node.js website|https://nodejs.org/]].
+# Update npm to the latest version by running the following command in your terminal: <<.copy-code-to-clipboard "npm install -g npm@latest">>
+# Clear the npm cache by running the following command in your terminal: <<.copy-code-to-clipboard "npm cache clean --force">>
+# Delete the `node_modules` folder in your TiddlyWiki directory by running the following command in your terminal: <<.copy-code-to-clipboard "rm -rf node_modules">>
+# Reinstall the dependencies by running the following command in your terminal: <<.copy-code-to-clipboard "npm install">>
+# If you continue to encounter errors, try running the following command in your terminal: <<.copy-code-to-clipboard "npm rebuild">>
+# If you are still experiencing issues, you may need to manually install the `gyp` and `prebuild` dependencies. You can do this by running the following commands in your terminal: <<.copy-code-to-clipboard "npm install -g node-gyp">> <<.copy-code-to-clipboard "npm install -g prebuild">>
+# Once you have installed the dependencies, try reinstalling the TiddlyWiki dependencies by running the following command in your terminal: <<.copy-code-to-clipboard "npm install">>

editions/multiwikidocs/tiddlers/Troubleshooting.tid

@@ -0,0 +1,4 @@
+title: Troubleshooting
+tags: TableOfContents
+
+<<list-links "[tag[Troubleshooting]]">>