From 7964272c98fec4d83d8432f372b6718f850c2c8c Mon Sep 17 00:00:00 2001 From: Oneric Date: Mon, 19 Feb 2024 17:33:14 +0100 Subject: [PATCH 1/2] Document how to avoid data loss on migration from Pleroma --- docs/docs/installation/migrating_to_akkoma.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/docs/installation/migrating_to_akkoma.md b/docs/docs/installation/migrating_to_akkoma.md index 9c30d9586..40eb6cac8 100644 --- a/docs/docs/installation/migrating_to_akkoma.md +++ b/docs/docs/installation/migrating_to_akkoma.md @@ -21,6 +21,33 @@ fork of Akkoma - luckily this isn't very hard. You'll need to update the backend, then possibly the frontend, depending on your setup. +## Backup diverging features + +As time goes on Akkoma and Pleroma added or removed different features +and reorganised the database in a different way. If you want to be able to +migrate back to Pleroma without losing any affected data, you’ll want to +make a backup before starting the migration. +If you're not interested in migrating back, skip this section +*(although it might be a good idea to temporarily keep a full DB backup +just in case something unexpected happens during migration)* + +As of 2024-02 you will want to keep a backup of: + +- the entire `chats` and `chat_message_references` tables + +The following columns are not deleted by a migration to Akkoma, but a migration +back to Pleroma or future Akkoma upgrades might affect them, so perhaps back them up as well: + +- the `birthday` of users and their `show_birthday` setting +- the `expires_at` key of in the `user_relationships` table + *(used by temporary mutes)* + +The way cached instance metadata is stored differs, but since those +will be refetched and updated anyway, there’s no need for a backup. + +Best check all newer migrations unique to Akkoma/Pleroma +to get an up-to-date picture of what needs to be kept. + ## From Source If you're running the source Akkoma install, you'll need to set the @@ -130,3 +157,4 @@ MIX_ENV=prod mix ecto.rollback --to 20210416051708 ``` Then switch back to Pleroma for updates (similar to how was done to migrate to Akkoma), and remove the front-ends. The front-ends are installed in the `frontends` folder in the [static directory](../configuration/static_dir.md). Once you are back to Pleroma, you will need to run the database migrations again. See the Pleroma documentation for this. +After this use your previous backups to restore data from diverging features. From bff2812a939c03c099117962283f28049667ac30 Mon Sep 17 00:00:00 2001 From: Oneric Date: Mon, 19 Feb 2024 17:53:11 +0100 Subject: [PATCH 2/2] More prominently document db migrations in migrations from Pleroma By now most instance will run a version past 2022-08 but the guide only documented it for from source installs and Pleroma develop. --- docs/docs/installation/migrating_to_akkoma.md | 44 ++++++++++++++----- 1 file changed, 32 insertions(+), 12 deletions(-) diff --git a/docs/docs/installation/migrating_to_akkoma.md b/docs/docs/installation/migrating_to_akkoma.md index 40eb6cac8..bf6eeebc7 100644 --- a/docs/docs/installation/migrating_to_akkoma.md +++ b/docs/docs/installation/migrating_to_akkoma.md @@ -61,16 +61,7 @@ git pull -r # to run "git merge stable" instead (or develop if you want) ``` -### WARNING - Migrating from Pleroma Develop -If you are on pleroma develop, and have updated since 2022-08, you may have issues with database migrations. - -Please roll back the given migrations: - -```bash -MIX_ENV=prod mix ecto.rollback --migrations-path priv/repo/optional_migrations/pleroma_develop_rollbacks -n5 -``` - -Then compile, migrate and restart as usual. +And compile as usual. ## From OTP @@ -80,15 +71,44 @@ This will just be setting the update URL - find your flavour from the [mapping o export FLAVOUR=[the flavour you found above] ./bin/pleroma_ctl update --zip-url https://akkoma-updates.s3-website.fr-par.scw.cloud/stable/akkoma-$FLAVOUR.zip -./bin/pleroma_ctl migrate ``` -Then restart. When updating in the future, you canjust use +When updating in the future, you can just use ```bash ./bin/pleroma_ctl update --branch stable ``` + +## Database Migrations +### WARNING - Migrating from Pleroma past 2022-08 +If you are on Pleroma stable >= 2.5.0 or Pleroma develop, and +have updated since 2022-08, you may have issues with database migrations. + +Please first roll back the given migrations: + +=== "OTP" + ```bash + ./bin/pleroma_ctl rollback --migrations-path priv/repo/optional_migrations/pleroma_develop_rollbacks -n5 + ``` +=== "From Source" + ```bash + MIX_ENV=prod mix ecto.rollback --migrations-path priv/repo/optional_migrations/pleroma_develop_rollbacks -n5 + ``` + +### Applying Akkoma Database Migrations + +Just run + +=== "OTP" + ```bash + ./bin/pleroma_ctl migrate + ``` +=== "From Source" + ```bash + MIX_ENV=prod mix ecto.migrate + ``` + ## Frontend changes Akkoma comes with a few frontend changes as well as backend ones,