From 5b956369934e448db285eb5f3e890f280cfa87de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20Franke?= Date: Sun, 5 Oct 2025 14:43:09 +0200 Subject: [PATCH] [docs] Add db migration tip for slow hardware instances. (#4457) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR adds a new section to the documentation to contain workarounds for running GtS on slow hardware. Right now it only contains a procedure on how to run migrations on a different database instance in case the original database is too slow to finish a database migration in a timely manner. Reviewed-on: https://codeberg.org/superseriousbusiness/gotosocial/pulls/4457 Co-authored-by: Daniël Franke Co-committed-by: Daniël Franke --- docs/admin/slow_hardware.md | 43 +++++++++++++++++++++++++++++++++++++ mkdocs.yml | 3 ++- 2 files changed, 45 insertions(+), 1 deletion(-) create mode 100644 docs/admin/slow_hardware.md diff --git a/docs/admin/slow_hardware.md b/docs/admin/slow_hardware.md new file mode 100644 index 000000000..8ba5a6f86 --- /dev/null +++ b/docs/admin/slow_hardware.md @@ -0,0 +1,43 @@ +# Managing GtS on slow hardware + +While GoToSocial runs great on lower-end hardware, some operations are not practical on it, especially +instances with the database on slow storage (think anything that is not an SSD). This document +offers some suggestions on how to work around common issues when running GtS on slow hardware. + +## Running database migrations on a different machine + +Sometimes a database migration will need to do operations that are taxing on the database's storage. +These operations can take days if the database resides on a hard disk or SD card. If your +database is on slow storage, it can save a lot of time to follow the following procedure: + +!!! danger + + It might seem tempting to keep GtS running while you run the migrations on another machine, but + doing this will lead to all the posts that are received during the migration post disappearing + once the migrated database is re-imported. + + 1. Shut down GtS + 2. Take a [backup](backup_and_restore.md#what-to-backup-database) of the database + 3. Import the database on faster hardware + 4. Run the GtS migration on the faster hardware + 5. Take a backup of the resultant database + 6. Import the resultant backup and overwrite the old database + 7. Start GtS with the new version + +### Running GtS migrations separately + +After you import the database on the faster hardware, you can run the migration without starting +GtS by downloading the *target* GtS version from the [releases](https://codeberg.org/superseriousbusiness/gotosocial/releases) page. +For instance, if you are running `v0.19.2` and you want to upgrade to `v0.20.0-rc1`, download the +latter version. Once you have the binary, set it to executable by running `chmod u+x /path/to/gotosocial`. Afterwards, copy the configuration of the original server, and alter +it with the location of the new database. We copy the configuration in case variables like +the hostname is used in the migration, we want to keep that consistent. +Once everything is in place, you can run the migration like this: + +```sh +$ /path/to/gotosocial --config-path /path/to/config migrations run +``` + +This will run all the migrations, just like GtS would if it was started normally. Once this is done +you can copy the result to the original instance and start the new GtS version there as well, which +will see that everything is migrated and that there's nothing to do except run as expected. diff --git a/mkdocs.yml b/mkdocs.yml index 5c33d764e..0d5528080 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -38,7 +38,7 @@ plugins: extra: alternate: - name: English - link: /en/ + link: /en/ lang: en - name: 中文 link: /zh-cn/ @@ -149,6 +149,7 @@ nav: - "admin/spam.md" - "admin/database_maintenance.md" - "admin/themes.md" + - "admin/slow_hardware.md" - "Federation": - "federation/index.md" - "federation/http_signatures.md"