From d9256707f414cb566ef9763572b5e2ab87135555 Mon Sep 17 00:00:00 2001 From: Jeremy Ruston Date: Mon, 18 Nov 2024 12:25:07 +0000 Subject: [PATCH] Add troubleshooting instructions --- .../tiddlers/Database Engines.tid | 15 +++++++++++++++ .../tiddlers/Installation using Git.tid | 4 +++- .../multiwikidocs/tiddlers/Installation.tid | 6 ++++-- ...oting gyp-prebuild Installation Errors.tid | 19 +++++++++++++++++++ .../tiddlers/Troubleshooting.tid | 4 ++++ 5 files changed, 45 insertions(+), 3 deletions(-) create mode 100644 editions/multiwikidocs/tiddlers/Database Engines.tid create mode 100644 editions/multiwikidocs/tiddlers/Troubleshooting gyp-prebuild Installation Errors.tid create mode 100644 editions/multiwikidocs/tiddlers/Troubleshooting.tid diff --git a/editions/multiwikidocs/tiddlers/Database Engines.tid b/editions/multiwikidocs/tiddlers/Database Engines.tid new file mode 100644 index 000000000..257bea34f --- /dev/null +++ b/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">> diff --git a/editions/multiwikidocs/tiddlers/Installation using Git.tid b/editions/multiwikidocs/tiddlers/Installation using Git.tid index 741a3eb50..2bbd2dd24 100644 --- a/editions/multiwikidocs/tiddlers/Installation using Git.tid +++ b/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 ctrl-C +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">> diff --git a/editions/multiwikidocs/tiddlers/Installation.tid b/editions/multiwikidocs/tiddlers/Installation.tid index 4e4fd258a..735e884d3 100644 --- a/editions/multiwikidocs/tiddlers/Installation.tid +++ b/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 ctrl-C -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. diff --git a/editions/multiwikidocs/tiddlers/Troubleshooting gyp-prebuild Installation Errors.tid b/editions/multiwikidocs/tiddlers/Troubleshooting gyp-prebuild Installation Errors.tid new file mode 100644 index 000000000..5da0ece6b --- /dev/null +++ b/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">> diff --git a/editions/multiwikidocs/tiddlers/Troubleshooting.tid b/editions/multiwikidocs/tiddlers/Troubleshooting.tid new file mode 100644 index 000000000..92ea1421c --- /dev/null +++ b/editions/multiwikidocs/tiddlers/Troubleshooting.tid @@ -0,0 +1,4 @@ +title: Troubleshooting +tags: TableOfContents + +<>