squeegily/pleroma
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

docs: remove overoptimistic OTP benefits and use tabs in migration from source

Browse Source
This commit is contained in:
rinpatch 2019-12-09 20:08:31 +03:00
parent b0505b2cc7
commit 0a8b32a661
1 changed files with 18 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
docs/installation/migrating_from_source_otp_en.md
View File

@ -1,42 +1,28 @@
# Switching a from-source install to OTP releases # Switching a from-source install to OTP releases
## What are 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. 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.
* **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 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, check the [Detecting flavour](otp_en.md#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 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 ## Pre-requisites
You will be running commands as root. If you aren't root already, please elevate your priviledges by executing `sudo su`/`su`. 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. The system needs to have `curl` and `unzip` installed for downloading and unpacking release builds.
Debian/Ubuntu: ```sh tab="Alpine"
```sh apk add curl unzip
```
```sh tab="Debian/Ubuntu"
apt install curl unzip apt install curl unzip
``` ```
Alpine:
```
apk add curl unzip
```
## Moving content out of the application directory ## 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. 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. Pleroma should be stopped before proceeding.
### Moving uploads/custom public files directory ### Moving uploads/custom public files directory
```sh ```sh
# Create uploads directory and set proper permissions (skip if using a remote uploader) # 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 # Note: It does not have to be `/var/lib/pleroma/uploads`, you can configure it to be something else later
@ -92,8 +78,8 @@ Before proceeding, get the flavour from [Detecting flavour](otp_en.md#detecting-
rm -r ~pleroma/* rm -r ~pleroma/*
# Set the flavour environment variable to the string you got in Detecting flavour section. # 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 # For example if the flavour is `amd64-musl` the command will be
export FLAVOUR="arm64-musl" export FLAVOUR="amd64-musl"
# Clone the release build into a temporary directory and unpack it # Clone the release build into a temporary directory and unpack it
# Replace `stable` with `unstable` if you want to run the unstable branch # Replace `stable` with `unstable` if you want to run the unstable branch
@ -124,8 +110,15 @@ OTP releases have different service files than from-source installs so they need
**Warning:** The service files assume pleroma user's home directory is `/opt/pleroma`, please make sure all paths fit your installation. **Warning:** The service files assume pleroma user's home directory is `/opt/pleroma`, please make sure all paths fit your installation.
Debian/Ubuntu: ```sh tab="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
```
```sh tab="Debian/Ubuntu"
# Copy the service into a proper directory # Copy the service into a proper directory
cp ~pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service cp ~pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service
@ -139,14 +132,6 @@ systemctl reenable pleroma
systemctl 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 ## Running mix tasks
Refer to [Running mix tasks](otp_en.md#running-mix-tasks) section from OTP release installation guide. Refer to [Running mix tasks](otp_en.md#running-mix-tasks) section from OTP release installation guide.
## Updating ## Updating