From 096767bb3b59b31106bd8fddd27e17cc234caf5a Mon Sep 17 00:00:00 2001
From: tobi <31960611+tsmethurst@users.noreply.github.com>
Date: Sun, 13 Oct 2024 21:51:31 +0200
Subject: [PATCH] [chore/docs] Add `/gotosocial/.cache` to Docker container,
 document `GTS_WAZERO_COMPILATION_CACHE` (#3425)

* [chore/docs] Add `/gotosocial/.cache` to Docker container, document `GTS_WAZERO_COMPILATION_CACHE`

* update wazero artifact size guesstimate
---
 Dockerfile                                    |  7 ++---
 docs/configuration/index.md                   | 16 ++++++++++++
 .../getting_started/installation/container.md | 26 +++++++++++++++++++
 example/docker-compose/docker-compose.yaml    | 16 ++++++++++++
 example/gotosocial.service                    |  9 +++++++
 5 files changed, 71 insertions(+), 3 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index 9ca0b2a28..df4fc56da 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -39,9 +39,10 @@ USER 1000:1000
 #
 # See https://docs.docker.com/engine/reference/builder/#workdir
 #
-# First make sure storage exists + is owned by 1000:1000, then go back
-# to just /gotosocial, where we'll run from
+# First make sure storage + cache exist and are owned by 1000:1000,
+# then go back to just /gotosocial, where we'll actually run from.
 WORKDIR "/gotosocial/storage"
+WORKDIR "/gotosocial/.cache"
 WORKDIR "/gotosocial"
 
 # copy the dist binary created by goreleaser or build.sh
@@ -51,5 +52,5 @@ COPY --chown=1000:1000 gotosocial /gotosocial/gotosocial
 COPY --chown=1000:1000 --from=bundler web /gotosocial/web
 COPY --chown=1000:1000 --from=swagger /go/src/github.com/superseriousbusiness/gotosocial/swagger.yaml web/assets/swagger.yaml
 
-VOLUME [ "/gotosocial/storage" ]
+VOLUME [ "/gotosocial/storage", "/gotosocial/.cache" ]
 ENTRYPOINT [ "/gotosocial/gotosocial", "server", "start" ]
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
index e869f6471..211ccfaea 100644
--- a/docs/configuration/index.md
+++ b/docs/configuration/index.md
@@ -126,3 +126,19 @@ This means in cases where you want to just try changing one thing, but don't wan
 Reasonable default values are provided for *most* of the configuration parameters, except in cases where a custom value is absolutely required.
 
 See the [example config file](https://github.com/superseriousbusiness/gotosocial/blob/main/example/config.yaml) for the default values, or run `gotosocial --help`.
+
+## `GTS_WAZERO_COMPILATION_CACHE`
+
+On startup, GoToSocial compiles embedded WebAssembly `ffmpeg` and `ffprobe` binaries into [Wazero](https://wazero.io/)-compatible modules, which are used for media processing without requiring any external dependencies.
+
+To speed up startup time of GoToSocial, you can cache the compiled modules between restarts so that GoToSocial doesn't have to compile them on every startup from scratch.
+
+You can instruct GoToSocial on where to store the Wazero artifacts by setting the environment variable `GTS_WAZERO_COMPILATION_CACHE` to a directory, which will be used by GtS to store two smallish artifacts of ~50MiB or so each (~100MiB total).
+
+For an example of this in action, see the [docker-compose.yaml](https://raw.githubusercontent.com/superseriousbusiness/gotosocial/main/example/docker-compose/docker-compose.yaml), and the [gotosocial.service](https://raw.githubusercontent.com/superseriousbusiness/gotosocial/main/example/gotosocial.service) example files.
+
+If you want to provide this value to GtS outside of systemd or Docker, you can do so in the following manner when starting up your GtS server:
+
+```bash
+GTS_WAZERO_COMPILATION_CACHE=~/gotosocial/.cache ./gotosocial --config-path ./config.yaml server start
+```
diff --git a/docs/getting_started/installation/container.md b/docs/getting_started/installation/container.md
index ff98c4105..58b5a810a 100644
--- a/docs/getting_started/installation/container.md
+++ b/docs/getting_started/installation/container.md
@@ -91,6 +91,32 @@ If you want to use [LetsEncrypt](../../configuration/tls.md) for TLS certificate
     
     For help translating variable names from the config.yaml file to environment variables, refer to the [configuration section](../../configuration/index.md#environment-variables).
 
+### Wazero Compilation Cache (optional)
+
+On startup, GoToSocial compiles embedded WebAssembly `ffmpeg` and `ffprobe` binaries into [Wazero](https://wazero.io/)-compatible modules, which are used for media processing without requiring any external dependencies.
+
+To speed up startup time of GoToSocial, you can cache the compiled modules between restarts so that GoToSocial doesn't have to compile them on every startup from scratch.
+
+If you'd like to do this in your Docker container, first create a `.cache` directory in your working folder to store the modules:
+
+```bash
+mkdir -p ~/gotosocial/.cache
+```
+
+Then, uncomment the second volume in the docker-compose.yaml file by removing the leading `#` symbol, so that instead of
+
+```yaml
+#- ~/gotosocial/.cache:/gotosocial/.cache
+```
+
+it reads
+
+```yaml
+- ~/gotosocial/.cache:/gotosocial/.cache
+```
+
+This will instruct Docker to mount the `~/gotosocial/.cache` directory at `/gotosocial/.cache` inside the Docker container.
+
 ## Start GoToSocial
 
 With those small changes out of the way, you can now start GoToSocial with the following command:
diff --git a/example/docker-compose/docker-compose.yaml b/example/docker-compose/docker-compose.yaml
index fc80348b2..05896d724 100644
--- a/example/docker-compose/docker-compose.yaml
+++ b/example/docker-compose/docker-compose.yaml
@@ -8,11 +8,21 @@ services:
     networks:
       - gotosocial
     environment:
+      # Change this to your actual host value.
       GTS_HOST: example.org
       GTS_DB_TYPE: sqlite
+      # Path in the GtS Docker container where
+      # the sqlite.db file will be stored.
       GTS_DB_ADDRESS: /gotosocial/storage/sqlite.db
+      # Change this to true if you're not running
+      # GoToSocial behind a reverse proxy.
       GTS_LETSENCRYPT_ENABLED: "false"
+      # Set your email address here if you
+      # want to receive letsencrypt notices.
       GTS_LETSENCRYPT_EMAIL_ADDRESS: ""
+      # Path in the GtS Docker container where the
+      # Wazero compilation cache will be stored.
+      GTS_WAZERO_COMPILATION_CACHE: /gotosocial/.cache
       ## For reverse proxy setups:
       # GTS_TRUSTED_PROXIES: "172.x.x.x"
       ## Set the timezone of your server:
@@ -24,7 +34,13 @@ services:
       ## For reverse proxy setups:
       #- "127.0.0.1:8080:8080"
     volumes:
+      # Your data volume, for your
+      # sqlite.db file and media files.
       - ~/gotosocial/data:/gotosocial/storage
+      # OPTIONAL: To mount volume for the WAZERO
+      # compilation cache, for speedier restart
+      # times, uncomment the below line:
+      #- ~/gotosocial/.cache:/gotosocial/.cache
     restart: "always"
 
 networks:
diff --git a/example/gotosocial.service b/example/gotosocial.service
index 37a66c66e..b59f6b5a6 100644
--- a/example/gotosocial.service
+++ b/example/gotosocial.service
@@ -13,6 +13,15 @@ Group=gotosocial
 Type=exec
 Restart=on-failure
 
+# For speedier restart times, you can uncomment the following Environment line to have GoToSocial cache compiled
+# Wazero artifacts in the given directory between restarts, so that it doesn't need to compile on startup every time.
+#
+# You may need to change the exact path depending on where you've got GoToSocial installed, for example if you've
+# installed at "~/gotosocial" then change the value to "GTS_WAZERO_COMPILATION_CACHE=~/gotosocial/.cache".
+#
+# Whatever you do, make sure the dir exists and that the gotosocial user has permission to write + read from it.
+#Environment="GTS_WAZERO_COMPILATION_CACHE=/gotosocial/.cache"
+
 # change if your path to the GoToSocial binary is different
 ExecStart=/gotosocial/gotosocial --config-path config.yaml server start
 WorkingDirectory=/gotosocial