|
| 1 | +# Upgrading |
| 2 | + |
| 3 | +This file shows all steps in how to upgrade between "versions" of the lemmy-ansible repository. |
| 4 | + |
| 5 | +While we specify a version of Lemmy, pict-rs, postgres, etc. at the point in time we make a release, it does not mean that you cannot mix-and-match versions. (ie; you can run pictrs 0.5.10 with Lemmy 0.19.3). |
| 6 | + |
| 7 | +While you are not forced into running the specific versions, we do not go through thorough testing on all version compatibility matrices, so please make your best judgement and always backup before performing updates. |
| 8 | + |
| 9 | +### Upgrading to 1.5.0 (Lemmy 0.19.4, Pict-rs 0.5, postgres 16) |
| 10 | + |
| 11 | +> **DO NOT RUN IT WITHOUT READING THIS WHOLE SECTION** |
| 12 | +
|
| 13 | +This is a major release which requires you to update postgres to v16, and pictrs to v0.5. Once that is done proceed with your regular deployments. |
| 14 | + |
| 15 | +#### Postgres Upgrade from v15 to v16 |
| 16 | + |
| 17 | +You need to migrate from postgres v15 to v16. A helper script is provided, that dumps your database, swaps postgres container versions, starts them, and then imports the backup into the new container. |
| 18 | + |
| 19 | +There will be downtime, and it is a little scary as it will be deleting the `volumes/postgres` folder. The only backup you have during this time will be the `15_16_dump.sql`, created by the helper script. |
| 20 | + |
| 21 | +On my reference instance (4 CPU, 8GB Memory, 30GB volumes/postgres), it took 10 minutes to dump the backup, and another 20 minutes to import it again. The biggest time sink when importing is when it recreates the indexes. |
| 22 | +If you have a faster system and no noisy neighbours you could get the dump and import to be below 20 minutes, but I'd aim for a 60 minute maintenace window. |
| 23 | + |
| 24 | +- The script you need to download and push onto your server: [postgres_15_to_16_upgrade.sh](https://github.com/LemmyNet/lemmy/blob/main/scripts/postgres_15_to_16_upgrade.sh). |
| 25 | + |
| 26 | +``` |
| 27 | +# Go to your lemmy directory with the docker-compose.yml |
| 28 | +cd /srv/lemmy/{my_lemmy_domain}/ |
| 29 | +
|
| 30 | +# Download the upgrade script |
| 31 | +sudo wget -O postgres_15_to_16_upgrade.sh "https://raw.githubusercontent.com/LemmyNet/lemmy/main/scripts/postgres_15_to_16_upgrade.sh" |
| 32 | +
|
| 33 | +# Run the script. Be aware that it may take > 20 minutes |
| 34 | +sudo sh postgres_15_to_16_upgrade.sh |
| 35 | +``` |
| 36 | + |
| 37 | +- This also creates a backup file of your old database, called `15_16_dump.sql`. **Do not delete this file** until you are sure that everything is working correctly, for at least a few days. |
| 38 | + |
| 39 | +#### Pictrs 0.4 -> 0.5 Upgrade |
| 40 | + |
| 41 | +`0.19.4` also adds functionality only supported by pictrs version `0.5`. Follow the [v0.4 -> v0.5 migration guide](https://git.asonix.dog/asonix/pict-rs.git#0-4-to-0-5-migration-guide) to make sure that your pictrs env vars in `vars.yml` are correct. |
| 42 | + |
| 43 | +There are more detailed pictrs upgrade instructions below. |
| 44 | + |
| 45 | +#### Steps |
| 46 | + |
| 47 | +- `git checkout main && git pull && git checkout 1.5.0` |
| 48 | +- Check the diff between the two versions to see the changes our examples: |
| 49 | + - examples/customPostgresql.conf: We added a new autoexplain & stats feature, & enabled jit after v16 upgrade. \ |
| 50 | + - On low memory systems, you might want to disable jit still: `jit=0` |
| 51 | + - examples/hosts: Add `lemmy_web_port` to have a dedicated port |
| 52 | + - examples/vars.yml: Add `postgres_shm` to have the correct shared memory for postgres |
| 53 | +- Confirm you are already running Postgres v16 |
| 54 | +- Run your regular deployment. Example: `ansible-playbook -i inventory/hosts lemmy.yml --become` |
| 55 | + |
| 56 | +### Upgrading to 1.4.0 (Lemmy 0.19.3 & Pict-rs 0.5.4) |
| 57 | + |
| 58 | +This is a semi-major release which upgrades pict-rs to 0.5 which has support for postgres as a backend. This configuration is **not supported** by lemmy-ansible for the moment. |
| 59 | + |
| 60 | +#### Steps |
| 61 | + |
| 62 | +- `git pull && git checkout 1.4.0` |
| 63 | +- Read [Pictrs' Configuration Changes](https://git.asonix.dog/asonix/pict-rs/#configuration-updates) |
| 64 | +- Amend your `vars.yml` file to respect the new changes |
| 65 | + - Optional: Add: `PICTRS__UPGRADE__CONCURRENCY` with a value between 32 and 512 depending on how much RAM/CPU you want to dedicate to the upgrade process. A value of 32 used about 2.5GB of RAM for the migration. |
| 66 | + - Optional: Curl `/internal/prepare_upgrade` to minimise downtime while upgrading. See [the instructions below](https://github.com/LemmyNet/lemmy-ansible#update-your-pict-rs-sled-database-optional) or the official documentation [here](https://git.asonix.dog/asonix/pict-rs/releases#user-content-upgrade-preparation-endpoint) |
| 67 | +- Run your regular deployment. Example: `ansible-playbook -i inventory/hosts lemmy.yml --become` |
| 68 | + |
| 69 | +### Upgrading to 1.3.1 (Lemmy 0.19.1) |
| 70 | + |
| 71 | +This is a very minor release but fixes issues relating to federation as part of the Lemmy update. |
| 72 | + |
| 73 | +#### Steps |
| 74 | + |
| 75 | +- `git pull && git checkout 1.3.1` |
| 76 | +- Run your regular deployment. Example: `ansible-playbook -i inventory/hosts lemmy.yml --become` |
| 77 | + |
| 78 | +### Upgrading to 1.3.0 (Lemmy 0.19.0 & Pict-rs 0.4.7) |
| 79 | + |
| 80 | +This is a major change and has required reading! tl;dr |
| 81 | + |
| 82 | +- Lemmy has been upgraded to 0.19.0 |
| 83 | +- pict-rs has been upgraded to 0.4.7 |
| 84 | + - pict-rs has not been integrated with postgres yet |
| 85 | +- "Optional Modules" are now available to be added to your lemmy install as provided by the community. |
| 86 | + - The first being pictrs-safety |
| 87 | + |
| 88 | +#### Steps |
| 89 | + |
| 90 | +- Prepare to have downtime as the database needs to perform migrations! |
| 91 | +- Run `git pull && git checkout 1.3.0` |
| 92 | +- Run your regular deployment. Example: `ansible-playbook -i inventory/hosts lemmy.yml --become` |
| 93 | +- Lemmy will now be down! In testing this takes from 20 to 60 minutes. |
| 94 | + - If you are bored you can ssh into your server, and check the logs on postgres for updates |
| 95 | + - `docker compose logs -f postgres` while ssh'd and in your Lemmy directory |
| 96 | + |
| 97 | +#### Update your pict-rs sled-database (Optional) |
| 98 | + |
| 99 | +If you are happy for pict-rs to be down _for a while_ ~go straight to our `1.3.1` git tag which updates pictrs to 0.5.0~. Otherwise keep reading. |
| 100 | +Starting with 0.5.0 your database will automatically upgrade to the latest version, which will cause downtime for your users. |
| 101 | +As such there is an intermediary step where you can upgrade your database in the background to prepare for 0.5 (Reference documentation)[https://git.asonix.dog/asonix/pict-rs/releases#user-content-upgrade-preparation-endpoint]. This ensure no-one is caught out by unforseen downtime of multiple services. |
| 102 | + |
| 103 | +Once you have deployed lemmy-ansible `1.3.0` tag, please continue (if you want): |
| 104 | + |
| 105 | +- Take note of what your pict-rs API Key is under `vars.yml` |
| 106 | +- Take note of what your docker network name is. (It's normally the domain without any extra characters) |
| 107 | + - You should be able to find it via: `docker network ls | grep _default` if in doubt. |
| 108 | +- Run the following command replacing `api-key` with the pict-rs api key, & `youdomain` with the network name. |
| 109 | +- `docker run --network yourdomain_default --rm curlimages/curl:8.5.0 --silent -XPOST -H'X-Api-Token: api-key' 'http://pictrs:8080/internal/prepare_upgrade'` |
| 110 | +- This will start the background process updating your database from 0.4 to 0.5 compatible. |
| 111 | + |
| 112 | +This is only Optional, and takes a shorter amount of time than the Lemmy database upgrade, but on huge installations it may take a lot longer. |
| 113 | + |
| 114 | +#### Optional Module(s) |
| 115 | + |
| 116 | +Our first optional module is [pictrs-safety](https://github.com/db0/pictrs-safety). See the repo linked for more information, especially for integration with pictrs (which is what it is for) Thanks to @db0 for their contribution. |
| 117 | +See the `pictrs_safety_env_vars` under `examples/vars.yml` for relevant options (and the two password variables) |
| 118 | +To enable this module to be used you must ADD `pictrs_safety: true` to your `vars.yml`. |
| 119 | + |
| 120 | +### Upgrading to 1.2.1 (Lemmy 0.18.5) |
| 121 | + |
| 122 | +This is a minor change which fixes the issue with the Postgres container not using the `customPostgres.conf` file. |
| 123 | + |
| 124 | +#### Steps |
| 125 | + |
| 126 | +- Please regenerate your `customPostgres.conf` from `examples/customPostgres.conf` |
| 127 | +- **OR** |
| 128 | +- Add the following block to your current customPostgres file. |
| 129 | + |
| 130 | +``` |
| 131 | +
|
| 132 | +# Listen beyond localhost |
| 133 | +
|
| 134 | +listen_addresses = '\*' |
| 135 | +
|
| 136 | +``` |
| 137 | + |
| 138 | +### Upgrading to 1.2.0 (Lemmy 0.18.5) |
| 139 | + |
| 140 | +Major changes: |
| 141 | + |
| 142 | +- All variables are not under a singular file so you will not need to modify anything: `inventory/host_vars/{{ domain }}/vars.yml` |
| 143 | +- `--become` is now optional instead of forced on |
| 144 | + |
| 145 | +#### Steps |
| 146 | + |
| 147 | +- Run `git pull && git checkout 1.2.0` |
| 148 | +- When upgrading from older versions of these playbooks, you will need to do the following: |
| 149 | + - Rename `inventory/host_vars/{{ domain }}/passwords/postgres` file to `inventory/host_vars/{{ domain }}/passwords/postgres.psk` |
| 150 | + - Copy the `examples/vars.yml` file to `inventory/host_vars/{{ domain }}/vars.yml` |
| 151 | + - Edit your variables as desired |
| 152 | +- Run your regular deployment. Example: `ansible-playbook -i inventory/hosts lemmy.yml --become` |
| 153 | + |
| 154 | +### Upgrading to 1.1.0 (Lemmy 0.18.3) |
| 155 | + |
| 156 | +- No major changes should be required |
0 commit comments