From 687f0aee51ad5ed4483317febe47be3f0685992c Mon Sep 17 00:00:00 2001 From: rinpatch Date: Mon, 24 Jun 2019 11:51:02 +0300 Subject: Basic skeleton of "Switching a from-source install to OTP releases" --- docs/installation/migrating_from_source_otp_en.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 docs/installation/migrating_from_source_otp_en.md (limited to 'docs/installation/migrating_from_source_otp_en.md') diff --git a/docs/installation/migrating_from_source_otp_en.md b/docs/installation/migrating_from_source_otp_en.md new file mode 100644 index 000000000..2f7a450d6 --- /dev/null +++ b/docs/installation/migrating_from_source_otp_en.md @@ -0,0 +1,18 @@ +# Switching a from-source install to OTP releases +## Why would one want to switch? +Benefits of OTP releases over from-source installs include: +* Less space used. OTP releases come without source code, build tools, have docs and debug symbols stripped from the compiled bytecode and do not cointain tests (100mb because of all the fixtures) and docs. +* Minimal system dependencies. Excluding the database and reverse proxy, all you need to download and run a release is `curl`, `unzip` and `ncurses`. Because Erlang runtime and Elixir are shipped with Pleroma, one can use the latest BEAM optimizations and Pleroma features, without having to worry about outdated system repos or a missing `erlang-*` package. +* Potentially less bugs and better performance. This extends on the previous point, because we have control over exactly what gets shipped, we can tweak the VM arguments and forget about weird bugs due to Erlang/Elixir version mismatches. +* Faster and less bug-prone mix tasks. On a from-source install one has to wait untill a new Pleroma node is started for each mix task and they execute outside of the instance context (for example if you deleted a user via a mix task, the instance will have no knowledge of that and continue to display status count and follows before the cache expires). Mix tasks in OTP releases are executed by calling into a running instance via RPC, which solves both of these problems. + +### Sounds great, how do I switch? +Currently we support Linux machines with GNU (e.g. Debian, Ubuntu) or musl (e.g. Alpine) libc and `x86_64`, `aarch64` or `armv7l` CPUs. If you are unsure you can check the [Detecting flavour](otp_en.html#detecting-flavour) section in OTP install guide. If your platform is supported, proceed with the guide, if not check the [My platform is not supported](#my-platform-is-not-supported) section. +### I don't think it is worth the effort, can I stay on a from-source install? +Yes, currently there are no plans to deprecate them. +### My platform is not supported +If you believe your platform is a popular choice for running Pleroma instances, or has the potential to become one you can [file an issue on our Gitlab](https://git.pleroma.social/pleroma/pleroma/issues/new). If not, guides on how to build and update releases by yourself will be available soon. +## Moving uploads/instance static directory +## Moving emoji +## Moving the config +## Installing the release -- cgit v1.2.3 From 57d18b06ab2b763922a7894aece982adf97c139e Mon Sep 17 00:00:00 2001 From: rinpatch Date: Tue, 25 Jun 2019 04:55:41 +0300 Subject: Remove the useless specification of test size and make the main points bold --- docs/installation/migrating_from_source_otp_en.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/installation/migrating_from_source_otp_en.md') diff --git a/docs/installation/migrating_from_source_otp_en.md b/docs/installation/migrating_from_source_otp_en.md index 2f7a450d6..ab140767e 100644 --- a/docs/installation/migrating_from_source_otp_en.md +++ b/docs/installation/migrating_from_source_otp_en.md @@ -1,10 +1,10 @@ # Switching a from-source install to OTP releases ## Why would one want to switch? Benefits of OTP releases over from-source installs include: -* Less space used. OTP releases come without source code, build tools, have docs and debug symbols stripped from the compiled bytecode and do not cointain tests (100mb because of all the fixtures) and docs. -* Minimal system dependencies. Excluding the database and reverse proxy, all you need to download and run a release is `curl`, `unzip` and `ncurses`. Because Erlang runtime and Elixir are shipped with Pleroma, one can use the latest BEAM optimizations and Pleroma features, without having to worry about outdated system repos or a missing `erlang-*` package. -* Potentially less bugs and better performance. This extends on the previous point, because we have control over exactly what gets shipped, we can tweak the VM arguments and forget about weird bugs due to Erlang/Elixir version mismatches. -* Faster and less bug-prone mix tasks. On a from-source install one has to wait untill a new Pleroma node is started for each mix task and they execute outside of the instance context (for example if you deleted a user via a mix task, the instance will have no knowledge of that and continue to display status count and follows before the cache expires). Mix tasks in OTP releases are executed by calling into a running instance via RPC, which solves both of these problems. +* **Less space used.** OTP releases come without source code, build tools, have docs and debug symbols stripped from the compiled bytecode and do not cointain tests and docs. +* **Minimal system dependencies.** Excluding the database and reverse proxy, all you need to download and run a release is `curl`, `unzip` and `ncurses`. Because Erlang runtime and Elixir are shipped with Pleroma, one can use the latest BEAM optimizations and Pleroma features, without having to worry about outdated system repos or a missing `erlang-*` package. +* **Potentially less bugs and better performance.** This extends on the previous point, because we have control over exactly what gets shipped, we can tweak the VM arguments and forget about weird bugs due to Erlang/Elixir version mismatches. +* **Faster and less bug-prone mix tasks.** On a from-source install one has to wait untill a new Pleroma node is started for each mix task and they execute outside of the instance context (for example if you deleted a user via a mix task, the instance will have no knowledge of that and continue to display status count and follows before the cache expires). Mix tasks in OTP releases are executed by calling into a running instance via RPC, which solves both of these problems. ### Sounds great, how do I switch? Currently we support Linux machines with GNU (e.g. Debian, Ubuntu) or musl (e.g. Alpine) libc and `x86_64`, `aarch64` or `armv7l` CPUs. If you are unsure you can check the [Detecting flavour](otp_en.html#detecting-flavour) section in OTP install guide. If your platform is supported, proceed with the guide, if not check the [My platform is not supported](#my-platform-is-not-supported) section. -- cgit v1.2.3 From 44aa895b78f7b37372df4b2ec2e4ba1177516a28 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Tue, 25 Jun 2019 05:50:25 +0300 Subject: Add a note that OTP releases don't contain revision history --- docs/installation/migrating_from_source_otp_en.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/installation/migrating_from_source_otp_en.md') diff --git a/docs/installation/migrating_from_source_otp_en.md b/docs/installation/migrating_from_source_otp_en.md index ab140767e..33e1eaaf0 100644 --- a/docs/installation/migrating_from_source_otp_en.md +++ b/docs/installation/migrating_from_source_otp_en.md @@ -1,7 +1,7 @@ # Switching a from-source install to OTP releases ## Why would one want to switch? Benefits of OTP releases over from-source installs include: -* **Less space used.** OTP releases come without source code, build tools, have docs and debug symbols stripped from the compiled bytecode and do not cointain tests and docs. +* **Less space used.** OTP releases come without source code, build tools, have docs and debug symbols stripped from the compiled bytecode and do not cointain tests, docs, revision history. * **Minimal system dependencies.** Excluding the database and reverse proxy, all you need to download and run a release is `curl`, `unzip` and `ncurses`. Because Erlang runtime and Elixir are shipped with Pleroma, one can use the latest BEAM optimizations and Pleroma features, without having to worry about outdated system repos or a missing `erlang-*` package. * **Potentially less bugs and better performance.** This extends on the previous point, because we have control over exactly what gets shipped, we can tweak the VM arguments and forget about weird bugs due to Erlang/Elixir version mismatches. * **Faster and less bug-prone mix tasks.** On a from-source install one has to wait untill a new Pleroma node is started for each mix task and they execute outside of the instance context (for example if you deleted a user via a mix task, the instance will have no knowledge of that and continue to display status count and follows before the cache expires). Mix tasks in OTP releases are executed by calling into a running instance via RPC, which solves both of these problems. -- cgit v1.2.3 From e404335af8fc214b84f9fe633830ba549bd322f7 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Wed, 26 Jun 2019 11:34:58 +0300 Subject: Add all the remaining sections to Switching to OTP releases --- docs/installation/migrating_from_source_otp_en.md | 137 ++++++++++++++++++++-- 1 file changed, 130 insertions(+), 7 deletions(-) (limited to 'docs/installation/migrating_from_source_otp_en.md') diff --git a/docs/installation/migrating_from_source_otp_en.md b/docs/installation/migrating_from_source_otp_en.md index 33e1eaaf0..0f790b4df 100644 --- a/docs/installation/migrating_from_source_otp_en.md +++ b/docs/installation/migrating_from_source_otp_en.md @@ -2,17 +2,140 @@ ## Why would one want to switch? Benefits of OTP releases over from-source installs include: * **Less space used.** OTP releases come without source code, build tools, have docs and debug symbols stripped from the compiled bytecode and do not cointain tests, docs, revision history. -* **Minimal system dependencies.** Excluding the database and reverse proxy, all you need to download and run a release is `curl`, `unzip` and `ncurses`. Because Erlang runtime and Elixir are shipped with Pleroma, one can use the latest BEAM optimizations and Pleroma features, without having to worry about outdated system repos or a missing `erlang-*` package. +* **Minimal system dependencies.** Excluding the database and reverse proxy, only `curl`, `unzip` and `ncurses` are needed to download and run the release. Because Erlang runtime and Elixir are shipped with Pleroma, one can use the latest BEAM optimizations and Pleroma features, without having to worry about outdated system repos or a missing `erlang-*` package. * **Potentially less bugs and better performance.** This extends on the previous point, because we have control over exactly what gets shipped, we can tweak the VM arguments and forget about weird bugs due to Erlang/Elixir version mismatches. -* **Faster and less bug-prone mix tasks.** On a from-source install one has to wait untill a new Pleroma node is started for each mix task and they execute outside of the instance context (for example if you deleted a user via a mix task, the instance will have no knowledge of that and continue to display status count and follows before the cache expires). Mix tasks in OTP releases are executed by calling into a running instance via RPC, which solves both of these problems. +* **Faster and less bug-prone mix tasks.** On a from-source install one has to wait untill a new Pleroma node is started for each mix task and they execute outside of the instance context (for example if a user was deleted via a mix task, the instance will have no knowledge of that and continue to display status count and follows before the cache expires). Mix tasks in OTP releases are executed by calling into a running instance via RPC, which solves both of these problems. ### Sounds great, how do I switch? -Currently we support Linux machines with GNU (e.g. Debian, Ubuntu) or musl (e.g. Alpine) libc and `x86_64`, `aarch64` or `armv7l` CPUs. If you are unsure you can check the [Detecting flavour](otp_en.html#detecting-flavour) section in OTP install guide. If your platform is supported, proceed with the guide, if not check the [My platform is not supported](#my-platform-is-not-supported) section. +Currently we support Linux machines with GNU (e.g. Debian, Ubuntu) or musl (e.g. Alpine) libc and `x86_64`, `aarch64` or `armv7l` CPUs. If you are unsure, check the [Detecting flavour](otp_en.html#detecting-flavour) section in OTP install guide. If your platform is supported, proceed with the guide, if not check the [My platform is not supported](#my-platform-is-not-supported) section. ### I don't think it is worth the effort, can I stay on a from-source install? Yes, currently there are no plans to deprecate them. + ### My platform is not supported -If you believe your platform is a popular choice for running Pleroma instances, or has the potential to become one you can [file an issue on our Gitlab](https://git.pleroma.social/pleroma/pleroma/issues/new). If not, guides on how to build and update releases by yourself will be available soon. -## Moving uploads/instance static directory -## Moving emoji -## Moving the config +If you think your platform is a popular choice for running Pleroma instances, or has the potential to become one, you can [file an issue on our Gitlab](https://git.pleroma.social/pleroma/pleroma/issues/new). If not, guides on how to build and update releases by yourself will be available soon. +## Pre-requisites +You will be running commands as root. If you aren't root already, please elevate your priviledges by executing `sudo su`/`su`. + +The system needs to have `curl` and `unzip` installed for downloading and unpacking release builds. + +Debian/Ubuntu: +```sh +apt install curl unzip +``` +Alpine: +``` +apk add curl unzip + +``` +## Moving content out of the application directory +When using OTP releases the application directory changes with every version so it would be a bother to keep content there (and also dangerous unless `--no-rm` option is used when updating). Fortunately almost all paths in Pleroma are configurable, so it is possible to move them out of there. + +Pleroma should be stopped before proceeding. + +### Moving uploads/custom public files directory +```sh +# Create uploads directory and set proper permissions (skip if using a remote uploader) +# Note: It does not have to be `/var/lib/pleroma/uploads`, you can configure it to be something else later +mkdir -p /var/lib/pleroma/uploads +chown -R pleroma /var/lib/pleroma + +# Create custom public files directory +# Note: It does not have to be `/var/lib/pleroma/static`, you can configure it to be something else later +mkdir -p /var/lib/pleroma/static +chown -R pleroma /var/lib/pleroma + +# If you use the local uploader with default settings your uploads should be located in `~pleroma/uploads` +mv ~pleroma/uploads /var/lib/pleroma/uploads + +# If you have created the custom public files directory with default settings it should be located in `~pleroma/instance/static` +mv ~pleroma/instance/static /var/lib/pleroma/static +``` + +### Moving emoji +Assuming you have all emojis in subdirectories of `priv/static/emoji` moving them can be done with +```sh +mkdir /var/lib/pleroma/static/emoji +ls -d ~pleroma/priv/static/emoji/*/ | xargs -i sh -c 'mv "{}" "/var/lib/pleroma/static/emoji/$(basename {})"' +``` + +But, if for some reason you have custom emojis in the root directory you should copy the whole directory instead. +```sh +mv ~pleroma/priv/static/emoji /var/lib/pleroma/static/emoji +``` +and then copy custom emojis to `/var/lib/pleroma/static/emoji/custom`. + +This is needed because storing custom emojis in the root directory is deprecated, but if you just move them to `/var/lib/pleroma/static/emoji/custom` it will break emoji urls on old posts. + +Note that globs have been replaced with `pack_extensions`, so if your emojis are not in png/gif you should [modify the default value](config.html#emoji). + +### Moving the config +```sh +# Create the config directory +# The default path for Pleroma config is /etc/pleroma/config.exs +# but it can be set via PLEROMA_CONFIG_PATH environment variable +mkdir -p /etc/pleroma + +# Move the config file +mv ~pleroma/config/prod.secret.exs /etc/pleroma/config.exs + +# Change `use Mix.Config` at the top to `import Config` +$EDITOR /etc/pleroma/config.exs +``` ## Installing the release +```sh +# Delete all files in pleroma user's directory +rm -r ~pleroma/* + +# Clone the release build into a temporary directory and unpack it +su pleroma -s $SHELL -lc " +curl 'https://git.pleroma.social/api/v4/projects/2/jobs/artifacts/master/download?job=$FLAVOUR' -o /tmp/pleroma.zip +unzip /tmp/pleroma.zip -d /tmp/ +" + +# Move the release to the home directory and delete temporary files +su pleroma -s $SHELL -lc " +mv /tmp/release/* /opt/pleroma +rmdir /tmp/release +rm /tmp/pleroma.zip +" + +# Start the instance to verify that everything is working as expected +su pleroma -s $SHELL -lc "./bin/pleroma daemon" + +# Wait for about 20 seconds and query the instance endpoint, if it shows your uri, name and email correctly, you are configured correctly +sleep 20 && curl http://localhost:4000/api/v1/instance + +# Stop the instance +su pleroma -s $SHELL -lc "./bin/pleroma stop" +``` + +## Setting up a system service +OTP releases have different service files than from-source installs so they need to be copied over again. + +Debian/Ubuntu: +```sh +# Copy the service into a proper directory +cp ~pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service + +# Reload service files +systemctl reload-daemon + +# Reenable pleroma to start on boot +systemctl reenable pleroma + +# Start pleroma +systemctl start pleroma +``` + +Alpine: +```sh +# Copy the service into a proper directory +cp -f ~pleroma/installation/init.d/pleroma /etc/init.d/pleroma + +# Start pleroma +rc-service pleroma start +``` +## Running mix tasks +Refer to [Running mix tasks](otp_en.html#running-mix-tasks) section from OTP release installation guide. +## Updating +Refer to [Updating](otp_en.html#updating) section from OTP release installation guide. -- cgit v1.2.3 From 877f91c0c489a7c33a6078dab4d00ceffc4af659 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Wed, 26 Jun 2019 15:20:22 +0300 Subject: Do not assume ~pleroma == /opt/pleroma --- docs/installation/migrating_from_source_otp_en.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/installation/migrating_from_source_otp_en.md') diff --git a/docs/installation/migrating_from_source_otp_en.md b/docs/installation/migrating_from_source_otp_en.md index 0f790b4df..add71d6af 100644 --- a/docs/installation/migrating_from_source_otp_en.md +++ b/docs/installation/migrating_from_source_otp_en.md @@ -94,7 +94,7 @@ unzip /tmp/pleroma.zip -d /tmp/ # Move the release to the home directory and delete temporary files su pleroma -s $SHELL -lc " -mv /tmp/release/* /opt/pleroma +mv /tmp/release/* ~pleroma/ rmdir /tmp/release rm /tmp/pleroma.zip " -- cgit v1.2.3 From f5f1bb35c3736dd591f6689813c7fe95650e4bba Mon Sep 17 00:00:00 2001 From: rinpatch Date: Wed, 26 Jun 2019 15:24:06 +0300 Subject: Instructions on getting the flavour --- docs/installation/migrating_from_source_otp_en.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/installation/migrating_from_source_otp_en.md') diff --git a/docs/installation/migrating_from_source_otp_en.md b/docs/installation/migrating_from_source_otp_en.md index add71d6af..46dc7b53b 100644 --- a/docs/installation/migrating_from_source_otp_en.md +++ b/docs/installation/migrating_from_source_otp_en.md @@ -82,10 +82,15 @@ mv ~pleroma/config/prod.secret.exs /etc/pleroma/config.exs $EDITOR /etc/pleroma/config.exs ``` ## Installing the release +Before proceeding, get the flavour from [Detecting flavour](otp_en.html#detecting-flavour) section in OTP installation guide. ```sh # Delete all files in pleroma user's directory rm -r ~pleroma/* +# Set the flavour environment variable to the string you got in Detecting flavour section. +# For example if the flavour is `arm64-musl` the command will be +export FLAVOUR="arm64-musl" + # Clone the release build into a temporary directory and unpack it su pleroma -s $SHELL -lc " curl 'https://git.pleroma.social/api/v4/projects/2/jobs/artifacts/master/download?job=$FLAVOUR' -o /tmp/pleroma.zip -- cgit v1.2.3 From 4f44732100a23475a645d9e7070ca0a17934ee49 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Thu, 27 Jun 2019 09:45:13 +0300 Subject: Add a note on what OTP releases are --- docs/installation/migrating_from_source_otp_en.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/installation/migrating_from_source_otp_en.md') diff --git a/docs/installation/migrating_from_source_otp_en.md b/docs/installation/migrating_from_source_otp_en.md index 46dc7b53b..4d6f20ee0 100644 --- a/docs/installation/migrating_from_source_otp_en.md +++ b/docs/installation/migrating_from_source_otp_en.md @@ -1,4 +1,6 @@ # Switching a from-source install to OTP releases +## What are OTP releases? +OTP releases are as close as you can get to binary releases with Erlang/Elixir. The release is self-contained, and provides everything needed to boot it, it is easily administered via the provided shell script to open up a remote console, start/stop/restart the release, start in the background, send remote commands, and more. ## Why would one want to switch? Benefits of OTP releases over from-source installs include: * **Less space used.** OTP releases come without source code, build tools, have docs and debug symbols stripped from the compiled bytecode and do not cointain tests, docs, revision history. -- cgit v1.2.3 From eeb419e3a0e8ad97b0061f5da9938bbf4f52c5c9 Mon Sep 17 00:00:00 2001 From: rinpatch Date: Fri, 28 Jun 2019 09:41:34 +0300 Subject: Add a note about the develop branch --- docs/installation/migrating_from_source_otp_en.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/installation/migrating_from_source_otp_en.md') diff --git a/docs/installation/migrating_from_source_otp_en.md b/docs/installation/migrating_from_source_otp_en.md index 4d6f20ee0..0b41d0c0e 100644 --- a/docs/installation/migrating_from_source_otp_en.md +++ b/docs/installation/migrating_from_source_otp_en.md @@ -1,6 +1,8 @@ # Switching a from-source install to OTP releases ## What are OTP releases? OTP releases are as close as you can get to binary releases with Erlang/Elixir. The release is self-contained, and provides everything needed to boot it, it is easily administered via the provided shell script to open up a remote console, start/stop/restart the release, start in the background, send remote commands, and more. +### Can I still run the develop branch if I decide to use them? +Yes, we produce builds for every commit in `develop`. However `develop` is considered unstable, please don't use it in production because of faster access to new features, unless you need them as an app developer. ## Why would one want to switch? Benefits of OTP releases over from-source installs include: * **Less space used.** OTP releases come without source code, build tools, have docs and debug symbols stripped from the compiled bytecode and do not cointain tests, docs, revision history. @@ -94,6 +96,7 @@ rm -r ~pleroma/* export FLAVOUR="arm64-musl" # Clone the release build into a temporary directory and unpack it +# Replace `master` with `develop` if you want to run the develop branch su pleroma -s $SHELL -lc " curl 'https://git.pleroma.social/api/v4/projects/2/jobs/artifacts/master/download?job=$FLAVOUR' -o /tmp/pleroma.zip unzip /tmp/pleroma.zip -d /tmp/ -- cgit v1.2.3