From 058d414fff72be7116d53b92df654315223cf3a9 Mon Sep 17 00:00:00 2001 From: Francis Dinh Date: Fri, 2 Sep 2022 23:31:22 -0400 Subject: [PATCH] docs: add migration guide Includes tag-merge workflow from @toast 's post at https://mk.toast.cafe/notes/93o9n4tfsi --- docs/migrating.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 docs/migrating.md diff --git a/docs/migrating.md b/docs/migrating.md new file mode 100644 index 000000000..1d2ea5573 --- /dev/null +++ b/docs/migrating.md @@ -0,0 +1,59 @@ +# Migrating to FoundKey + +Migrating from Misskey to FoundKey is relatively straightforward. However, additional steps are required as there are significant changes between the two projects. + +## Backup +The process will take some time and it's possible something will go wrong. It's highly suggested to make a database dump using `pgdump` and backing up `.config/default.yml` and the `files/` directory before proceeding any further. + +## Reverting migrations +If you're migrating from Misskey 12.112.0 or higher, you'll need to revert some database migrations as they have diverged from that point. Specifically, you'll need to revert `nsfwDetection1655368940105` and newer migrations. + +Run the following to revert those migrations: +```sh +cd packages/backend + +LINE_NUM="$(npx typeorm migration:show -d ormconfig.js | grep -n nsfwDetection1655368940105 | cut -d ':' -f 1)" +NUM_MIGRATIONS="$(npx typeorm migration:show -d ormconfig.js | tail -n+"$LINE_NUM" | grep '\[X\]' | nl)" + +for i in $(seq 1 $NUM_MIGRAIONS); do + npx typeorm migration:revert -d ormconfig.js +done +``` + +## Switching repositories +To switch to the FoundKey repository, do the following in your Misskey install location: +```sh +git remote set-url origin https://akkoma.dev/FoundKeyGang/FoundKey.git +git fetch origin +``` +We recommend using a local branch and merging in upstream releases as they get tagged. This allows for easy local customization of your install. + +For example, say your local branch is `toast.cafe` and you want to use release `v13.0.0-preview1`. To create that branch: +```sh +git checkout tags/v13.0.0-preview1 -b toast.cafe +``` + +When a new release comes out, simply fetch and merge in the new tag. Here we opt to squash upstream commits as it allows for easy reverts in case something goes wrong. +```sh +git fetch -t +git merge tags/v13.0.0-preview2 --squash + # you are now on the "next" release +``` + +## Rebuilding and running database migrations +This will be pretty much the same as a regular update of Misskey. Note that `yarn install` may take a while since dependency versions have been updated or removed and we use a newer version of Yarn. +```sh +yarn install +NODE_ENV=production yarn build +yarn migrate +``` + +## Restarting your instance +To let the changes take effect restart your instance as usual: +```sh +# Systemd +systemctl restart misskey + +# OpenRC +rc-service misskey restart +```