docs/docs/administration/updating.md

@@ -3,15 +3,34 @@
 You should **always check the [release notes/changelog](https://akkoma.dev/AkkomaGang/akkoma/src/branch/develop/CHANGELOG.md)** in case there are config deprecations, special update steps, etc.
 
 Besides that, doing the following is generally enough:
+## Switch to the akkoma user
+```sh
+# Using sudo
+sudo -su akkoma
+
+# Using doas
+doas -su akkoma
+
+# Using su
+su -s "$SHELL" akkoma
+```
 
 ## For OTP installations
-
 ```sh
-# Download the new release
-su akkoma -s $SHELL -lc "./bin/pleroma_ctl update" 
+# Download latest stable release
+./bin/pleroma_ctl update --branch stable
 
-# Migrate the database, you are advised to stop the instance before doing that
-su akkoma -s $SHELL -lc "./bin/pleroma_ctl migrate"
+# Stop akkoma
+./bin/pleroma stop # or using the system service manager (e.g. systemctl stop akkoma)
+
+# Run database migrations
+./bin/pleroma_ctl migrate
+
+# Update frontend(s). See Frontend Configuration doc for more information.
+./bin/pleroma_ctl frontend install pleroma-fe --ref stable
+
+# Start akkoma
+./bin/pleroma daemon # or using the system service manager (e.g. systemctl start akkoma)
 ```
 
 If you selected an alternate flavour on installation, 
@@ -19,13 +38,28 @@ you _may_ need to specify `--flavour`, in the same way as
 [when installing](../../installation/otp_en#detecting-flavour).
 
 ## For from source installations (using git)
+Run as the `akkoma` user:
 
-1. Go to the working directory of Akkoma (default is `/opt/akkoma`)
-2. Run `git pull` [^1]. This pulls the latest changes from upstream.
-3. Run `mix deps.get` [^1]. This pulls in any new dependencies.
-4. Stop the Akkoma service.
-5. Run `mix ecto.migrate` [^1] [^2]. This task performs database migrations, if there were any.
-6. Start the Akkoma service.
+```sh
+# Pull in new changes
+git pull
 
-[^1]: Depending on which install guide you followed (for example on Debian/Ubuntu), you want to run `git` and `mix` tasks as `akkoma` user by adding `sudo -Hu akkoma` before the command.
-[^2]: Prefix with `MIX_ENV=prod` to run it using the production config file.
+# Run with production configuration
+export MIX_ENV=prod
+
+# Download and compile dependencies
+mix deps.get
+mix compile
+
+# Stop akkoma (replace with your system service manager's equivalent if different)
+sudo systemctl stop akkoma
+
+# Run database migrations
+mix ecto.migrate
+
+# Update frontend(s). See Frontend Configration doc for more information.
+mix pleroma.frontend install pleroma-fe --ref stable
+
+# Start akkoma (replace with your system service manager's equivalent if different)
+sudo systemctl start akkoma
+```