[docs] Document experimental, unsupported nowasm tag (#3436)

* [docs] Document experimental, unsupported `nowasm` tag

* change some awkward wording

README.md

@@ -294,17 +294,15 @@ Mostly works, just a few issues with WASM SQLite; check release notes carefully
 
 GtS doesn't work well on 32-bit systems like i386, or Armv6/v7, mainly due to performance of media decoding.
 
-As such, we don't recommend running GtS on 32-bit, but you may have success if you turn off downloading of remote media.
+We don't recommend running GtS on 32-bit, but you may have some success either turning off remote media processing altogether, or building a binary yourself with the totally **unsupported, experimental** [nowasm](https://docs.gotosocial.org/en/latest/advanced/builds/nowasm/) tag.
 
 For more guidance, check release notes when trying to install on 32-bit. 
 
 #### OpenBSD
 
 Marked as unsupported due to performance issues (high memory usage when idle, crashes while processing media).
 
-You may have some success if you turn off decoding of remote media.
-
-We hope to support OpenBSD better in future, but this is not guaranteed.
+While we don't support running GtS on OpenBSD, you may have some success building a binary yourself with the totally **unsupported, experimental** [nowasm](https://docs.gotosocial.org/en/latest/advanced/builds/nowasm/) tag.
 
 ### Stable Releases
 

docs/advanced/builds/nowasm.md

@@ -0,0 +1,27 @@
+# Build without Wazero / WASM
+
+!!! Danger "This is unsupported"
+    We do not offer any kind of support for deployments of GoToSocial built with the `nowasm` tag described in this section. Such builds should be considered strictly experimental, and any issues that come when running them are none of our business! Please don't open issues on the repo looking for help debugging deployments of `nowasm` builds.
+
+On [supported platforms](../../getting_started/releases.md#supported-platforms), GoToSocial uses the WebAssembly runtime [Wazero](https://wazero.io/) to sandbox `ffmpeg`, `ffprobe`, and `sqlite3` WebAssembly binaries, allowing these applications to be packaged and run inside the GoToSocial binary, without requiring admins to install + manage any external dependencies.
+
+This has the advantage of making it easier for admins to maintain their GoToSocial instance, as their GtS binary is completely isolated from any changes to their system-installed `ffmpeg`, `ffprobe`, and `sqlite`. It's also a bit safer to run `ffmpeg` in this way, as GoToSocial wraps the `ffmpeg` binary in a very constrained file system that doesn't permit the `ffmpeg` binary to access any files other than the ones it's decoding + reencoding. In other words, GoToSocial on supported platforms offers most of the functionality of `ffmpeg` and so on, without some of the headaches.
+
+However, not all platforms are capable of running Wazero in the much-faster "compiler" mode, and have to fall back to the very slow (and resource-heavy) "interpreter" mode. See [this table](https://github.com/tetratelabs/wazero?tab=readme-ov-file#conformance) from Wazero for conformance.
+
+"Interpreter" mode runs so poorly for GoToSocial's use case that it's simply not feasible to run a GoToSocial instance in a stable manner on platforms that aren't 64-bit Linux or 64-bit FreeBSD, as all the memory and CPU get gobbled up by media processing.
+
+However! To enable folks to run **experimental, unsupported deployments of GoToSocial**, we expose the `nowasm` build tag, which can be used to compile a build of GoToSocial that does not use Wazero or WASM at all.
+
+A GoToSocial binary built with `nowasm` will use the [modernc version of SQLite](https://pkg.go.dev/modernc.org/sqlite) instead of the WASM one, and will use on-system `ffmpeg` and `ffprobe` binaries for media processing.
+
+To build GoToSocial with the `nowasm` tag, you can pass the tag into our convenience `build.sh` script like so:
+
+```bash
+GO_BUILDTAGS=nowasm ./scripts/build.sh
+```
+
+In order to run a version of GoToSocial built in this way, you must ensure that `ffmpeg` and `ffprobe` are installed on the host. This is usually as simple as running a command like `doas -u root pkg_add ffmpeg` (OpenBSD), or `sudo apt install ffmpeg` (Debian etc.). 
+
+!!! Danger "No really though, it's unsupported"
+    Again, if running builds of GoToSocial with `nowasm` works for your OS/Arch combination, that's great, but we do not support such builds and we won't be able to help debugging why something doesn't work.

docs/advanced/index.md

@@ -1,6 +1,6 @@
 # Advanced
 
-In this section we touch on a number of more advanced topics, primarily related around deploying, operating and tuning GoToSocial.
+In this section we touch on a number of more advanced topics, primarily related around building, deploying, operating and tuning GoToSocial.
 
 We consider these topics advanced because applying them incorrectly does have the possibility of causing client and federation issues. Applying any of these configuration changes may also make it harder for you to debug an issue with your GoToSocial instance if you don't understand the changes that you're making.
 

mkdocs.yml

@@ -100,7 +100,7 @@ nav:
       - "configuration/advanced.md"
       - "configuration/observability.md"
   - "Advanced":
-    - "advanced/index.md"
+    - "Overview": "advanced/index.md"
     - "advanced/host-account-domain.md"
     - "advanced/outgoing-proxy.md"
     - "Caching":
@@ -117,6 +117,8 @@ nav:
     - "advanced/metrics.md"
     - "advanced/replicating-sqlite.md"
     - "advanced/sqlite-networked-storage.md"
+    - "Advanced builds":
+      - "advanced/builds/nowasm.md"
 
   - "Admin":
       - "admin/settings.md"