fix(migrations): make Rebased rollback safe
This commit is contained in:
Lain Soykaf
parent
e1e853e8f7
commit
478b021fbe
4 changed files with 276 additions and 37 deletions
|
|
@ -1,44 +1,130 @@
|
|||
# Migrating from Rebased
|
||||
|
||||
## Code migration
|
||||
Rebased and Pleroma currently have compatible database schemas, so removing
|
||||
Rebased-specific database objects is optional. The cleanup described below is
|
||||
destructive and can take a long time on large databases.
|
||||
|
||||
As Rebased only officially supported running from source code, we assume you're running it from source as well. To migrate source from upstream, you need to set the origin repository URL to upstream and pull the changes.
|
||||
This guide requires a Pleroma release that contains this document and native
|
||||
webhook support. If you are reading the development version of this guide
|
||||
before those changes reach `stable`, wait for the corresponding stable release.
|
||||
|
||||
## Prepare and back up
|
||||
|
||||
Plan a maintenance window and read the [backup guide](../administration/backup.md)
|
||||
before starting.
|
||||
|
||||
Stop Rebased and confirm it is stopped before making the backup. Omit the
|
||||
backup guide's final restart step and leave Rebased stopped:
|
||||
|
||||
```bash
|
||||
git remote set-url origin https://git.pleroma.social/pleroma/pleroma
|
||||
git pull -r
|
||||
sudo systemctl stop pleroma
|
||||
sudo systemctl is-active pleroma
|
||||
```
|
||||
|
||||
Then, install the dependencies and compile as usual:
|
||||
Make a verified database backup and a copy of the Rebased installation,
|
||||
including its configuration, uploads, and `instance` directory. Also save the
|
||||
current systemd unit if you plan to replace it.
|
||||
|
||||
## Install Pleroma
|
||||
|
||||
Do not use `git pull --rebase` to change an existing Rebased checkout into a
|
||||
Pleroma checkout. The forks use different branches, and rebasing can replay
|
||||
Rebased-specific commits over Pleroma. Move the old checkout aside and clone a
|
||||
clean copy of Pleroma instead. The paths below assume the default source
|
||||
installation in `/opt/pleroma`:
|
||||
|
||||
```bash
|
||||
MIX_ENV=prod mix deps.get
|
||||
MIX_ENV=prod mix compile
|
||||
sudo mv /opt/pleroma /opt/pleroma.rebased
|
||||
sudo mkdir /opt/pleroma
|
||||
sudo chown pleroma:pleroma /opt/pleroma
|
||||
sudo -Hu pleroma git clone -b stable https://git.pleroma.social/pleroma/pleroma /opt/pleroma
|
||||
```
|
||||
|
||||
As Rebased recommends using [`asdf` version manager](https://asdf-vm.com/), you might want to either keep using it or switch to system Elixir installation. If you choose the latter, follow Pleroma installation instructions for your distribution and replace the Pleroma systemd service with one provided by Pleroma upstream.
|
||||
Restore the instance-specific files from the old checkout. This usually
|
||||
includes `config/prod.secret.exs`, `config/prod.exported_from_db.secret.exs` if
|
||||
present, `uploads`, and `instance`. Diff and restore any other non-stock
|
||||
configuration files, preserve their ownership, and review them before starting
|
||||
Pleroma.
|
||||
|
||||
Pleroma requires Elixir 1.15 or newer. Install supported Erlang and Elixir
|
||||
versions as described in the installation guide for your distribution before
|
||||
running any Mix command. Do not reuse Rebased's `.tool-versions`. If you keep
|
||||
using [`asdf`](https://asdf-vm.com/), select supported versions in the
|
||||
`pleroma` user's home and use the asdf Mix shim for every command below.
|
||||
|
||||
Set `MIX` to the appropriate binary, verify the selected runtime, then install
|
||||
the dependencies and compile Pleroma:
|
||||
|
||||
```bash
|
||||
cd /opt/pleroma
|
||||
MIX=/usr/bin/mix
|
||||
# If using asdf instead:
|
||||
# MIX=/var/lib/pleroma/.asdf/shims/mix
|
||||
sudo -Hu pleroma "$MIX" --version
|
||||
sudo -Hu pleroma MIX_ENV=prod "$MIX" deps.get
|
||||
sudo -Hu pleroma MIX_ENV=prod "$MIX" compile
|
||||
```
|
||||
|
||||
Compare your existing systemd unit with `installation/pleroma.service`. If you
|
||||
replace it, review its user, paths, and environment first. Reload systemd after
|
||||
making changes:
|
||||
|
||||
```bash
|
||||
sudo cp /opt/pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service
|
||||
sudo systemctl daemon-reload
|
||||
```
|
||||
|
||||
Because Rebased doesn't come with a bundled frontend, you most likely have one installed in thhe `instance/static` directory. You can remove it, as Pleroma comes with a bundled frontend. Be sure not to remove other files you might have there, like custom emojis.
|
||||
Rebased does not bundle a frontend, so `instance/static` may contain an
|
||||
installed frontend. Pleroma includes a bundled frontend. You can remove the
|
||||
separately installed frontend after the migration, but do not remove other
|
||||
instance files such as custom emojis.
|
||||
|
||||
## Database migration
|
||||
|
||||
> Note: While it is not necessary to rollback Rebased-specific migrations because they don't include breaking changes, it is recommended to do so to keep the database clean. You will lose data related to Rebased-specific features, like the configured webhooks or user-defined location. Consider taking a backup.
|
||||
Rebased's extra columns, index, and enum labels do not prevent Pleroma from
|
||||
starting. Existing notifications with Rebased-only event types are not
|
||||
supported by Pleroma, however, and can cause notification API errors. Run the
|
||||
cleanup below, or archive and remove those notification rows separately before
|
||||
starting Pleroma. Skipping the cleanup preserves them if you need to restore
|
||||
Rebased.
|
||||
|
||||
To rollback Rebased-specific migrations:
|
||||
Pleroma supports Rebased's webhook schema. The cleanup does not roll back the
|
||||
shared webhook migrations, so webhook configuration is preserved.
|
||||
|
||||
To perform the optional cleanup, run the rollback while the service is stopped:
|
||||
|
||||
```bash
|
||||
MIX_ENV=prod mix ecto.rollback --migrations-path priv/repo/optional_migrations/rebased_rollbacks --all
|
||||
MIX=/usr/bin/mix
|
||||
# If using asdf instead:
|
||||
# MIX=/var/lib/pleroma/.asdf/shims/mix
|
||||
sudo -Hu pleroma MIX_ENV=prod "$MIX" ecto.rollback --migrations-path priv/repo/optional_migrations/rebased_rollbacks --all
|
||||
```
|
||||
|
||||
Then, just
|
||||
This deletes the Rebased-only `accepts_email_list`, `location`, and
|
||||
`last_move_at` user fields and the `pleroma:participation_accepted`,
|
||||
`pleroma:participation_request`, `pleroma:event_reminder`, and
|
||||
`pleroma:event_update` notifications. It also rewrites the notifications table
|
||||
and can require substantial time, free disk space, and write-ahead log capacity
|
||||
on a large instance.
|
||||
|
||||
Apply all pending Pleroma migrations:
|
||||
|
||||
```bash
|
||||
MIX_ENV=prod mix ecto.migrate
|
||||
sudo -Hu pleroma MIX_ENV=prod "$MIX" ecto.migrate
|
||||
```
|
||||
|
||||
to apply Pleroma database migrations.
|
||||
## Start and verify Pleroma
|
||||
|
||||
Start Pleroma and inspect its status and logs:
|
||||
|
||||
```bash
|
||||
sudo systemctl start pleroma
|
||||
sudo systemctl status pleroma
|
||||
sudo journalctl -u pleroma -n 100 --no-pager
|
||||
```
|
||||
|
||||
Verify that the instance, uploads, frontend, and webhook configuration work as
|
||||
expected before deleting `/opt/pleroma.rebased` or the database backup. If the
|
||||
migration fails, keep the service stopped and restore both the database backup
|
||||
and the previous checkout before restarting Rebased. If you changed the
|
||||
systemd unit or runtime setup, restore those too and run
|
||||
`systemctl daemon-reload` before restarting the service.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue