git.squeep.com Git - akkoma/blob - docs/installation/migrating_from_source_otp_en.md

   1 # Switching a from-source install to OTP releases
   2 ## Why would one want to switch?
   3 Benefits of OTP releases over from-source installs include:
   4 * **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.
   5 * **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.
   6 * **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.
   7 * **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.
   8
   9 ### Sounds great, how do I switch?
  10 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.
  11 ### I don't think it is worth the effort, can I stay on a from-source install?
  12 Yes, currently there are no plans to deprecate them.
  13
  14 ### My platform is not supported
  15 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.
  16 ## Pre-requisites
  17 You will be running commands as root. If you aren't root already, please elevate your priviledges by executing `sudo su`/`su`.
  18
  19 The system needs to have `curl` and `unzip` installed for downloading and unpacking release builds.
  20
  21 Debian/Ubuntu:
  22 ```sh
  23 apt install curl unzip
  24 ```
  25 Alpine:
  26 ```
  27 apk add curl unzip
  28
  29 ```
  30 ## Moving content out of the application directory
  31 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.
  32
  33 Pleroma should be stopped before proceeding.
  34
  35 ### Moving uploads/custom public files directory
  36 ```sh
  37 # Create uploads directory and set proper permissions (skip if using a remote uploader)
  38 # Note: It does not have to be `/var/lib/pleroma/uploads`, you can configure it to be something else later
  39 mkdir -p /var/lib/pleroma/uploads
  40 chown -R pleroma /var/lib/pleroma
  41
  42 # Create custom public files directory
  43 # Note: It does not have to be `/var/lib/pleroma/static`, you can configure it to be something else later
  44 mkdir -p /var/lib/pleroma/static
  45 chown -R pleroma /var/lib/pleroma
  46
  47 # If you use the local uploader with default settings your uploads should be located in `~pleroma/uploads`
  48 mv ~pleroma/uploads /var/lib/pleroma/uploads
  49
  50 # If you have created the custom public files directory with default settings it should be located in `~pleroma/instance/static`
  51 mv ~pleroma/instance/static /var/lib/pleroma/static
  52 ```
  53
  54 ### Moving emoji
  55 Assuming you have all emojis in subdirectories of `priv/static/emoji` moving them can be done with
  56 ```sh
  57 mkdir /var/lib/pleroma/static/emoji
  58 ls -d ~pleroma/priv/static/emoji/*/ | xargs -i sh -c 'mv "{}" "/var/lib/pleroma/static/emoji/$(basename {})"'
  59 ```
  60
  61 But, if for some reason you have custom emojis in the root directory you should copy the whole directory instead.
  62 ```sh
  63 mv ~pleroma/priv/static/emoji /var/lib/pleroma/static/emoji
  64 ```
  65 and then copy custom emojis to `/var/lib/pleroma/static/emoji/custom`.
  66
  67 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.
  68
  69 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).
  70
  71 ### Moving the config
  72 ```sh
  73 # Create the config directory
  74 # The default path for Pleroma config is /etc/pleroma/config.exs
  75 # but it can be set via PLEROMA_CONFIG_PATH environment variable
  76 mkdir -p /etc/pleroma
  77
  78 # Move the config file
  79 mv ~pleroma/config/prod.secret.exs /etc/pleroma/config.exs
  80
  81 # Change `use Mix.Config` at the top to `import Config`
  82 $EDITOR /etc/pleroma/config.exs
  83 ```
  84 ## Installing the release
  85 ```sh
  86 # Delete all files in pleroma user's directory
  87 rm -r ~pleroma/*
  88
  89 # Clone the release build into a temporary directory and unpack it
  90 su pleroma -s $SHELL -lc "
  91 curl 'https://git.pleroma.social/api/v4/projects/2/jobs/artifacts/master/download?job=$FLAVOUR' -o /tmp/pleroma.zip
  92 unzip /tmp/pleroma.zip -d /tmp/
  93 "
  94
  95 # Move the release to the home directory and delete temporary files
  96 su pleroma -s $SHELL -lc "
  97 mv /tmp/release/* /opt/pleroma
  98 rmdir /tmp/release
  99 rm /tmp/pleroma.zip
 100 "
 101
 102 # Start the instance to verify that everything is working as expected
 103 su pleroma -s $SHELL -lc "./bin/pleroma daemon"
 104
 105 # Wait for about 20 seconds and query the instance endpoint, if it shows your uri, name and email correctly, you are configured correctly
 106 sleep 20 && curl http://localhost:4000/api/v1/instance
 107
 108 # Stop the instance
 109 su pleroma -s $SHELL -lc "./bin/pleroma stop"
 110 ```
 111
 112 ## Setting up a system service
 113 OTP releases have different service files than from-source installs so they need to be copied over again.
 114
 115 Debian/Ubuntu:
 116 ```sh
 117 # Copy the service into a proper directory
 118 cp ~pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service
 119
 120 # Reload service files
 121 systemctl reload-daemon
 122
 123 # Reenable pleroma to start on boot
 124 systemctl reenable pleroma
 125
 126 # Start pleroma
 127 systemctl start pleroma
 128 ```
 129
 130 Alpine:
 131 ```sh
 132 # Copy the service into a proper directory
 133 cp -f ~pleroma/installation/init.d/pleroma /etc/init.d/pleroma
 134
 135 # Start pleroma
 136 rc-service pleroma start
 137 ```
 138 ## Running mix tasks
 139 Refer to [Running mix tasks](otp_en.html#running-mix-tasks) section from OTP release installation guide.
 140 ## Updating
 141 Refer to [Updating](otp_en.html#updating) section from OTP release installation guide.