From f676007b18f7df7efada72f688f1213fc6d02749 Mon Sep 17 00:00:00 2001 From: Stefan Date: Fri, 16 Dec 2022 17:23:31 +0100 Subject: [PATCH] clean-up docs to avoid mismatches in BE and FE. Clearly state that stable-versions are installed --- .../docs/administration/CLI_tasks/frontend.md | 7 +-- docs/docs/administration/updating.md | 62 ++++++++++++++----- docs/docs/installation/alpine_linux_en.md | 6 +- docs/docs/installation/arch_linux_en.md | 6 +- docs/docs/installation/debian_based_en.md | 6 +- docs/docs/installation/fedora_based_en.md | 6 +- docs/docs/installation/otp_redhat_en.md | 2 +- .../installation/verifying_otp_releases.md | 2 +- 8 files changed, 65 insertions(+), 32 deletions(-) diff --git a/docs/docs/administration/CLI_tasks/frontend.md b/docs/docs/administration/CLI_tasks/frontend.md index 1fadc921f..382ac268e 100644 --- a/docs/docs/administration/CLI_tasks/frontend.md +++ b/docs/docs/administration/CLI_tasks/frontend.md @@ -21,24 +21,23 @@ Currently, known `` values are: - [admin-fe](https://akkoma.dev/AkkomaGang/admin-fe) - [mastodon-fe](https://akkoma.dev/AkkomaGang/masto-fe) - [pleroma-fe](https://akkoma.dev/AkkomaGang/pleroma-fe) -- [soapbox-fe](https://gitlab.com/soapbox-pub/soapbox-fe) You can still install frontends that are not configured, see below. -## Example installations for a known frontend +## Example installations for a known frontend (Stable-Version) For a frontend configured under the `available` key, it's enough to install it by name. === "OTP" ```sh - ./bin/pleroma_ctl frontend install pleroma-fe + ./bin/pleroma_ctl frontend install pleroma-fe --ref stable ``` === "From Source" ```sh - mix pleroma.frontend install pleroma-fe + mix pleroma.frontend install pleroma-fe --ref stable ``` This will download the latest build for the pre-configured `ref` and install it. It can then be configured as the one of the served frontends in the config file (see `primary` or `admin`). diff --git a/docs/docs/administration/updating.md b/docs/docs/administration/updating.md index 2d9e77075..21ddb11d9 100644 --- a/docs/docs/administration/updating.md +++ b/docs/docs/administration/updating.md @@ -1,17 +1,36 @@ # Updating your instance -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. +You should **always check the [release notes/changelog](https://akkoma.dev/AkkomaGang/akkoma/src/branch/stable/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 Pleroma-FE frontend to latest stable. For other Frontends see Frontend Configration 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 Pleroma-FE frontend to latest stable. For other Frontends 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 +``` diff --git a/docs/docs/installation/alpine_linux_en.md b/docs/docs/installation/alpine_linux_en.md index aae8f9626..bdfb96d77 100644 --- a/docs/docs/installation/alpine_linux_en.md +++ b/docs/docs/installation/alpine_linux_en.md @@ -84,12 +84,12 @@ doas adduser -S -s /bin/false -h /opt/akkoma -H -G akkoma akkoma **Note**: To execute a single command as the Akkoma system user, use `doas -u akkoma command`. You can also switch to a shell by using `doas -su akkoma`. If you don’t have and want `doas` on your system, you can use `su` as root user (UID 0) for a single command by using `su -l akkoma -s $SHELL -c 'command'` and `su -l akkoma -s $SHELL` for starting a shell. -* Git clone the AkkomaBE repository and make the Akkoma user the owner of the directory: +* Git clone the AkkomaBE repository from stable-branch and make the Akkoma user the owner of the directory: ```shell doas mkdir -p /opt/akkoma doas chown -R akkoma:akkoma /opt/akkoma -doas -u akkoma git clone https://akkoma.dev/AkkomaGang/akkoma.git /opt/akkoma +doas -u akkoma git clone https://akkoma.dev/AkkomaGang/akkoma.git -b stable /opt/akkoma ``` * Change to the new directory: @@ -109,7 +109,7 @@ doas -u akkoma mix deps.get * This may take some time, because parts of akkoma get compiled first. * After that it will ask you a few questions about your instance and generates a configuration file in `config/generated_config.exs`. -* Check the configuration and if all looks right, rename it, so Akkoma will load it (`prod.secret.exs` for productive instance, `dev.secret.exs` for development instances): +* Check the configuration and if all looks right, rename it, so Akkoma will load it (`prod.secret.exs` for productive instances): ```shell doas -u akkoma mv config/{generated_config.exs,prod.secret.exs} diff --git a/docs/docs/installation/arch_linux_en.md b/docs/docs/installation/arch_linux_en.md index 639c9c798..300a5d80f 100644 --- a/docs/docs/installation/arch_linux_en.md +++ b/docs/docs/installation/arch_linux_en.md @@ -75,12 +75,12 @@ sudo useradd -r -s /bin/false -m -d /var/lib/akkoma -U akkoma **Note**: To execute a single command as the Akkoma system user, use `sudo -Hu akkoma command`. You can also switch to a shell by using `sudo -Hu akkoma $SHELL`. If you don’t have and want `sudo` on your system, you can use `su` as root user (UID 0) for a single command by using `su -l akkoma -s $SHELL -c 'command'` and `su -l akkoma -s $SHELL` for starting a shell. -* Git clone the AkkomaBE repository and make the Akkoma user the owner of the directory: +* Git clone the AkkomaBE repository from stable-branch and make the Akkoma user the owner of the directory: ```shell sudo mkdir -p /opt/akkoma sudo chown -R akkoma:akkoma /opt/akkoma -sudo -Hu akkoma git clone https://akkoma.dev/AkkomaGang/akkoma.git /opt/akkoma +sudo -Hu akkoma git clone https://akkoma.dev/AkkomaGang/akkoma.git -b stable /opt/akkoma ``` * Change to the new directory: @@ -100,7 +100,7 @@ sudo -Hu akkoma mix deps.get * This may take some time, because parts of akkoma get compiled first. * After that it will ask you a few questions about your instance and generates a configuration file in `config/generated_config.exs`. -* Check the configuration and if all looks right, rename it, so Akkoma will load it (`prod.secret.exs` for productive instance, `dev.secret.exs` for development instances): +* Check the configuration and if all looks right, rename it, so Akkoma will load it (`prod.secret.exs` for productive instances): ```shell sudo -Hu akkoma mv config/{generated_config.exs,prod.secret.exs} diff --git a/docs/docs/installation/debian_based_en.md b/docs/docs/installation/debian_based_en.md index 139c789bc..265658fef 100644 --- a/docs/docs/installation/debian_based_en.md +++ b/docs/docs/installation/debian_based_en.md @@ -49,12 +49,12 @@ sudo useradd -r -s /bin/false -m -d /var/lib/akkoma -U akkoma **Note**: To execute a single command as the Akkoma system user, use `sudo -Hu akkoma command`. You can also switch to a shell by using `sudo -Hu akkoma $SHELL`. If you don’t have and want `sudo` on your system, you can use `su` as root user (UID 0) for a single command by using `su -l akkoma -s $SHELL -c 'command'` and `su -l akkoma -s $SHELL` for starting a shell. -* Git clone the AkkomaBE repository and make the Akkoma user the owner of the directory: +* Git clone the AkkomaBE repository from stable-branch and make the Akkoma user the owner of the directory: ```shell sudo mkdir -p /opt/akkoma sudo chown -R akkoma:akkoma /opt/akkoma -sudo -Hu akkoma git clone https://akkoma.dev/AkkomaGang/akkoma.git /opt/akkoma +sudo -Hu akkoma git clone https://akkoma.dev/AkkomaGang/akkoma.git -b stable /opt/akkoma ``` * Change to the new directory: @@ -74,7 +74,7 @@ sudo -Hu akkoma mix deps.get * This may take some time, because parts of akkoma get compiled first. * After that it will ask you a few questions about your instance and generates a configuration file in `config/generated_config.exs`. -* Check the configuration and if all looks right, rename it, so Akkoma will load it (`prod.secret.exs` for productive instance, `dev.secret.exs` for development instances): +* Check the configuration and if all looks right, rename it, so Akkoma will load it (`prod.secret.exs` for productive instances): ```shell sudo -Hu akkoma mv config/{generated_config.exs,prod.secret.exs} diff --git a/docs/docs/installation/fedora_based_en.md b/docs/docs/installation/fedora_based_en.md index d8c7b3e74..a24a870a4 100644 --- a/docs/docs/installation/fedora_based_en.md +++ b/docs/docs/installation/fedora_based_en.md @@ -74,12 +74,12 @@ sudo useradd -r -s /bin/false -m -d /var/lib/akkoma -U akkoma **Note**: To execute a single command as the Akkoma system user, use `sudo -Hu akkoma command`. You can also switch to a shell by using `sudo -Hu akkoma $SHELL`. If you don’t have and want `sudo` on your system, you can use `su` as root user (UID 0) for a single command by using `su -l akkoma -s $SHELL -c 'command'` and `su -l akkoma -s $SHELL` for starting a shell. -* Git clone the AkkomaBE repository and make the Akkoma user the owner of the directory: +* Git clone the AkkomaBE repository from stable-branch and make the Akkoma user the owner of the directory: ```shell sudo mkdir -p /opt/akkoma sudo chown -R akkoma:akkoma /opt/akkoma -sudo -Hu akkoma git clone https://akkoma.dev/AkkomaGang/akkoma.git /opt/akkoma +sudo -Hu akkoma git clone https://akkoma.dev/AkkomaGang/akkoma.git -b stable /opt/akkoma ``` * Change to the new directory: @@ -99,7 +99,7 @@ sudo -Hu akkoma mix deps.get * This may take some time, because parts of akkoma get compiled first. * After that it will ask you a few questions about your instance and generates a configuration file in `config/generated_config.exs`. -* Check the configuration and if all looks right, rename it, so Akkoma will load it (`prod.secret.exs` for productive instance, `dev.secret.exs` for development instances): +* Check the configuration and if all looks right, rename it, so Akkoma will load it (`prod.secret.exs` for productive instances): ```shell sudo -Hu akkoma mv config/{generated_config.exs,prod.secret.exs} diff --git a/docs/docs/installation/otp_redhat_en.md b/docs/docs/installation/otp_redhat_en.md index ec6c30bcf..1490d3139 100644 --- a/docs/docs/installation/otp_redhat_en.md +++ b/docs/docs/installation/otp_redhat_en.md @@ -37,7 +37,7 @@ sudo dnf install git gcc g++ erlang elixir erlang-os_mon erlang-eldap erlang-xme ```shell cd ~ -git clone https://akkoma.dev/AkkomaGang/akkoma.git +git clone https://akkoma.dev/AkkomaGang/akkoma.git -b stable ``` * Change to the new directory: diff --git a/docs/docs/installation/verifying_otp_releases.md b/docs/docs/installation/verifying_otp_releases.md index 5f1ac6949..6e3c6f8ca 100644 --- a/docs/docs/installation/verifying_otp_releases.md +++ b/docs/docs/installation/verifying_otp_releases.md @@ -12,7 +12,7 @@ Release URLs will always be of the form https://akkoma-updates.s3-website.fr-par.scw.cloud/{branch}/akkoma-{flavour}.zip ``` -Where branch is usually `stable` or `develop`, and `flavour` is +Where branch is usually `stable` and `flavour` is the one [that you detect on install](../otp_en/#detecting-flavour). So, for an AMD64 stable install, your update URL will be