From c596ace9dfb1600f824a28b5d89e732fc164162f Mon Sep 17 00:00:00 2001 From: Phantasm Date: Sun, 14 Jun 2026 20:17:36 +0200 Subject: [PATCH 01/19] Woodpecker CI: Build API specs again --- .woodpecker/spec-build.yaml | 53 +++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 .woodpecker/spec-build.yaml diff --git a/.woodpecker/spec-build.yaml b/.woodpecker/spec-build.yaml new file mode 100644 index 000000000..f902914f4 --- /dev/null +++ b/.woodpecker/spec-build.yaml @@ -0,0 +1,53 @@ +when: + - event: tag + - event: manual + branch: stable + +labels: + platform: linux/amd64 + +variables: + artifacts_uploader_image: &artifacts_uploader_image docker.io/woodpeckercommunity/plugin-gitea-package:0.5.0 + artifacts_uploader_settings: &artifacts_uploader_settings + user: + from_secret: pleroma-ci-user + password: + from_secret: pleroma-ci-password + owner: 'pleroma' + +steps: + build-spec: + image: docker.io/hexpm/elixir-amd64:1.17.3-erlang-27.3.4.2-alpine-3.22.1 + environment: + MIX_ENV: prod + VIX_COMPILATION_MODE: PLATFORM_PROVIDED_LIBVIPS + commands: + - apk update --no-cache + - apk add git build-base cmake file-dev openssl vips-dev zip + - mix local.hex --force + - mix local.rebar --force + - mix deps.get --only prod + - mix pleroma.openapi_spec spec.json + + upload-spec: + image: *artifacts_uploader_image + settings: + <<: *artifacts_uploader_settings + package_name: api-docs-spec + package_version: stable + file_source: ./spec.json + file_name: spec.json + update: 'true' + + trigger-deploy: + image: docker.io/woodpeckerci/plugin-trigger:1.1.1 + settings: + params: + - BRANCH=stable + deploy: 'api-docs' + last-successful: true + token: + from_secret: + pleroma-ci-woodpecker-token + repositories: + - pleroma/api-docs@master From 71104db3f6e0bcd74e7150a475db9199abcb96e6 Mon Sep 17 00:00:00 2001 From: Phantasm Date: Fri, 19 Jun 2026 14:07:44 +0200 Subject: [PATCH 02/19] Woodpecker CI: Deploy docs on stable tag --- .woodpecker/docs.yaml | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 .woodpecker/docs.yaml diff --git a/.woodpecker/docs.yaml b/.woodpecker/docs.yaml new file mode 100644 index 000000000..99a32b598 --- /dev/null +++ b/.woodpecker/docs.yaml @@ -0,0 +1,21 @@ +when: + - event: tag + - event: manual + branch: stable + +labels: + platform: linux/amd64 + +skip_clone: true + +steps: + trigger-deploy: + image: docker.io/woodpeckerci/plugin-trigger:1.1.1 + settings: + deploy: 'docs' + last-successful: true + token: + from_secret: + pleroma-ci-woodpecker-token + repositories: + - pleroma/docs@master From e35dacf9f9d0f9c57d135b14cf8b3c59c13291d3 Mon Sep 17 00:00:00 2001 From: Phantasm Date: Fri, 19 Jun 2026 14:54:36 +0200 Subject: [PATCH 03/19] Woodpecker CI: pass branch to triggered docs workflows --- .woodpecker/docs.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.woodpecker/docs.yaml b/.woodpecker/docs.yaml index 99a32b598..e4a035171 100644 --- a/.woodpecker/docs.yaml +++ b/.woodpecker/docs.yaml @@ -12,6 +12,8 @@ steps: trigger-deploy: image: docker.io/woodpeckerci/plugin-trigger:1.1.1 settings: + params: + - BRANCH=stable deploy: 'docs' last-successful: true token: From d549b98f8babc01db442c39b247ec034537c9e3d Mon Sep 17 00:00:00 2001 From: Phantasm Date: Sun, 21 Jun 2026 18:35:48 +0200 Subject: [PATCH 04/19] changelog --- changelog.d/woodpecker-ci-docs.skip | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 changelog.d/woodpecker-ci-docs.skip diff --git a/changelog.d/woodpecker-ci-docs.skip b/changelog.d/woodpecker-ci-docs.skip new file mode 100644 index 000000000..e69de29bb From a050b00898db718e050d2da412dbae285dd79b0d Mon Sep 17 00:00:00 2001 From: Phantasm Date: Sat, 5 Sep 2026 20:48:08 +0200 Subject: [PATCH 05/19] Woodpecker CI Docs: Also build docs for develop branch --- .woodpecker/docs.yaml | 40 +++++++++++++++++++++++++++++++--------- 1 file changed, 31 insertions(+), 9 deletions(-) diff --git a/.woodpecker/docs.yaml b/.woodpecker/docs.yaml index e4a035171..6d4372c0f 100644 --- a/.woodpecker/docs.yaml +++ b/.woodpecker/docs.yaml @@ -1,23 +1,45 @@ when: + - event: push + branch: ${CI_REPO_DEFAULT_BRANCH} + path: [ "docs/**" ] - event: tag - event: manual - branch: stable + evaluate: 'CI_COMMIT_BRANCH == "stable" || CI_COMMIT_BRANCH == CI_REPO_DEFAULT_BRANCH' labels: platform: linux/amd64 skip_clone: true -steps: - trigger-deploy: - image: docker.io/woodpeckerci/plugin-trigger:1.1.1 - settings: - params: - - BRANCH=stable +variables: + trigger_settings: &trigger_settings deploy: 'docs' last-successful: true token: - from_secret: - pleroma-ci-woodpecker-token + from_secret: pleroma-ci-woodpecker-token repositories: - pleroma/docs@master + docker_image: &docker_image docker.io/woodpeckerci/plugin-trigger:1.1.1 + +steps: + trigger-deploy-stable: + when: + - event: tag + - event: manual + branch: stable + image: *docker_image + settings: + <<: *trigger_settings + params: + - BRANCH=stable + + trigger-deploy-develop: + when: + - event: push + - event: manual + branch: ${CI_REPO_DEFAULT_BRANCH} + image: *docker_image + settings: + <<: *trigger_settings + params: + - BRANCH=develop From c978fe0b7b3560853b69df7169922b87cbd32774 Mon Sep 17 00:00:00 2001 From: Phantasm Date: Sat, 5 Sep 2026 20:54:44 +0200 Subject: [PATCH 06/19] CI: Bump Gitea Package plugin version --- .woodpecker/spec-build.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.woodpecker/spec-build.yaml b/.woodpecker/spec-build.yaml index f902914f4..b5117a31f 100644 --- a/.woodpecker/spec-build.yaml +++ b/.woodpecker/spec-build.yaml @@ -7,7 +7,7 @@ labels: platform: linux/amd64 variables: - artifacts_uploader_image: &artifacts_uploader_image docker.io/woodpeckercommunity/plugin-gitea-package:0.5.0 + artifacts_uploader_image: &artifacts_uploader_image docker.io/woodpeckercommunity/plugin-gitea-package:0.5.1 artifacts_uploader_settings: &artifacts_uploader_settings user: from_secret: pleroma-ci-user From a881ffe8c22fa795a8681346eb2c0414c6a2dfec Mon Sep 17 00:00:00 2001 From: Phantasm Date: Sat, 5 Sep 2026 21:14:26 +0200 Subject: [PATCH 07/19] Woodpecker CI API spec: Update Elixir image to an existing one Switches from hexpm/elixir-amd64 to hexpm/elixir. --- .woodpecker/spec-build.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.woodpecker/spec-build.yaml b/.woodpecker/spec-build.yaml index b5117a31f..91151ce30 100644 --- a/.woodpecker/spec-build.yaml +++ b/.woodpecker/spec-build.yaml @@ -17,7 +17,7 @@ variables: steps: build-spec: - image: docker.io/hexpm/elixir-amd64:1.17.3-erlang-27.3.4.2-alpine-3.22.1 + image: docker.io/hexpm/elixir:1.17.3-erlang-27.3.4.17-alpine-3.22.5 environment: MIX_ENV: prod VIX_COMPILATION_MODE: PLATFORM_PROVIDED_LIBVIPS From 5452e3f73e136cb42931bff3ee09c5389db7e909 Mon Sep 17 00:00:00 2001 From: Phantasm Date: Sat, 5 Sep 2026 21:25:28 +0200 Subject: [PATCH 08/19] Fix indentation --- .woodpecker/docs.yaml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.woodpecker/docs.yaml b/.woodpecker/docs.yaml index 6d4372c0f..2a6023abd 100644 --- a/.woodpecker/docs.yaml +++ b/.woodpecker/docs.yaml @@ -13,12 +13,12 @@ skip_clone: true variables: trigger_settings: &trigger_settings - deploy: 'docs' - last-successful: true - token: - from_secret: pleroma-ci-woodpecker-token - repositories: - - pleroma/docs@master + deploy: 'docs' + last-successful: true + token: + from_secret: pleroma-ci-woodpecker-token + repositories: + - pleroma/docs@master docker_image: &docker_image docker.io/woodpeckerci/plugin-trigger:1.1.1 steps: From fd1b15dd5823bc0687f943e44ffdf612b764291a Mon Sep 17 00:00:00 2001 From: Lain Soykaf Date: Wed, 9 Sep 2026 13:21:07 +0400 Subject: [PATCH 09/19] fix(ci): isolate API documentation channels --- .woodpecker/spec-build.yaml | 79 ++++++++++++++++++++++++++++++------- 1 file changed, 64 insertions(+), 15 deletions(-) diff --git a/.woodpecker/spec-build.yaml b/.woodpecker/spec-build.yaml index 91151ce30..e294806f9 100644 --- a/.woodpecker/spec-build.yaml +++ b/.woodpecker/spec-build.yaml @@ -1,11 +1,21 @@ when: + - event: push + branch: ${CI_REPO_DEFAULT_BRANCH} + path: + - ".woodpecker/spec-build.yaml" + - "mix.exs" + - "mix.lock" + - "lib/pleroma/web.ex" + - "lib/pleroma/web/**/*.ex" - event: tag - event: manual - branch: stable + evaluate: 'CI_COMMIT_BRANCH == "stable" || CI_COMMIT_BRANCH == CI_REPO_DEFAULT_BRANCH' labels: platform: linux/amd64 +concurrency: 1 + variables: artifacts_uploader_image: &artifacts_uploader_image docker.io/woodpeckercommunity/plugin-gitea-package:0.5.1 artifacts_uploader_settings: &artifacts_uploader_settings @@ -14,6 +24,18 @@ variables: password: from_secret: pleroma-ci-password owner: 'pleroma' + package_name: api-docs-spec + file_source: ./spec.json + file_name: spec.json + update: 'true' + trigger_image: &trigger_image docker.io/woodpeckerci/plugin-trigger:1.1.1 + trigger_settings: &trigger_settings + deploy: 'api-docs' + last-successful: true + token: + from_secret: pleroma-ci-woodpecker-token + repositories: + - pleroma/api-docs@master steps: build-spec: @@ -33,21 +55,48 @@ steps: image: *artifacts_uploader_image settings: <<: *artifacts_uploader_settings - package_name: api-docs-spec - package_version: stable - file_source: ./spec.json - file_name: spec.json - update: 'true' + package_version: ${CI_COMMIT_SHA} - trigger-deploy: - image: docker.io/woodpeckerci/plugin-trigger:1.1.1 + upload-spec-stable: + when: + - event: tag + - event: manual + branch: stable + image: *artifacts_uploader_image settings: + <<: *artifacts_uploader_settings + package_version: stable + + upload-spec-develop: + when: + - event: push + - event: manual + branch: ${CI_REPO_DEFAULT_BRANCH} + image: *artifacts_uploader_image + settings: + <<: *artifacts_uploader_settings + package_version: develop + + trigger-deploy-stable: + when: + - event: tag + - event: manual + branch: stable + image: *trigger_image + settings: + <<: *trigger_settings params: - BRANCH=stable - deploy: 'api-docs' - last-successful: true - token: - from_secret: - pleroma-ci-woodpecker-token - repositories: - - pleroma/api-docs@master + - SPEC_VERSION=${CI_COMMIT_SHA} + + trigger-deploy-develop: + when: + - event: push + - event: manual + branch: ${CI_REPO_DEFAULT_BRANCH} + image: *trigger_image + settings: + <<: *trigger_settings + params: + - BRANCH=develop + - SPEC_VERSION=${CI_COMMIT_SHA} From 239ae3403b39d6b6074d2588a38466ae2df914af Mon Sep 17 00:00:00 2001 From: Lain Soykaf Date: Wed, 9 Sep 2026 15:55:18 +0400 Subject: [PATCH 10/19] fix(ci): pass API deployment parameters separately --- .woodpecker/spec-build.yaml | 9 +++++---- changelog.d/woodpecker-trigger-params.skip | 0 2 files changed, 5 insertions(+), 4 deletions(-) create mode 100644 changelog.d/woodpecker-trigger-params.skip diff --git a/.woodpecker/spec-build.yaml b/.woodpecker/spec-build.yaml index e294806f9..0024a62f1 100644 --- a/.woodpecker/spec-build.yaml +++ b/.woodpecker/spec-build.yaml @@ -50,6 +50,9 @@ steps: - mix local.rebar --force - mix deps.get --only prod - mix pleroma.openapi_spec spec.json + - | + printf 'BRANCH=stable\nSPEC_VERSION=%s\n' "$${CI_COMMIT_SHA}" > trigger-deploy-stable.params + printf 'BRANCH=develop\nSPEC_VERSION=%s\n' "$${CI_COMMIT_SHA}" > trigger-deploy-develop.params upload-spec: image: *artifacts_uploader_image @@ -86,8 +89,7 @@ steps: settings: <<: *trigger_settings params: - - BRANCH=stable - - SPEC_VERSION=${CI_COMMIT_SHA} + - trigger-deploy-stable.params trigger-deploy-develop: when: @@ -98,5 +100,4 @@ steps: settings: <<: *trigger_settings params: - - BRANCH=develop - - SPEC_VERSION=${CI_COMMIT_SHA} + - trigger-deploy-develop.params diff --git a/changelog.d/woodpecker-trigger-params.skip b/changelog.d/woodpecker-trigger-params.skip new file mode 100644 index 000000000..e69de29bb From f61cf55676bf011a0bfb8a203aa0fafacfb2dfed Mon Sep 17 00:00:00 2001 From: Phantasm Date: Mon, 21 Sep 2026 21:47:53 +0200 Subject: [PATCH 11/19] Docs: Add newer Elixir/Erlang versions installation documentation Also splits generic dependencies into elixir/erlang and the rest. Generic depenencies then import the elixir/erlang snippets to preserve previous layout. --- .../installing_newer_elixir_erlang.add | 1 + .../erlang_elixir_requirements.include | 2 + .../installation/generic_dependencies.include | 7 +- .../installing_newer_elixir_erlang.md | 288 ++++++++++++++++++ 4 files changed, 296 insertions(+), 2 deletions(-) create mode 100644 changelog.d/installing_newer_elixir_erlang.add create mode 100644 docs/installation/erlang_elixir_requirements.include create mode 100644 docs/installation/installing_newer_elixir_erlang.md diff --git a/changelog.d/installing_newer_elixir_erlang.add b/changelog.d/installing_newer_elixir_erlang.add new file mode 100644 index 000000000..e49aaeb21 --- /dev/null +++ b/changelog.d/installing_newer_elixir_erlang.add @@ -0,0 +1 @@ +Docs: Added documentation for installing newer version of Elixir/Erlang than what distro ships diff --git a/docs/installation/erlang_elixir_requirements.include b/docs/installation/erlang_elixir_requirements.include new file mode 100644 index 000000000..aa336dfe9 --- /dev/null +++ b/docs/installation/erlang_elixir_requirements.include @@ -0,0 +1,2 @@ +* Elixir >=1.15.0, <1.20 +* Erlang OTP >=24.0.0 (supported: <29) diff --git a/docs/installation/generic_dependencies.include b/docs/installation/generic_dependencies.include index 382f07a6c..86dbc6838 100644 --- a/docs/installation/generic_dependencies.include +++ b/docs/installation/generic_dependencies.include @@ -1,8 +1,7 @@ ## Required dependencies +{! backend/installation/erlang_elixir_requirements.include !} * PostgreSQL >=11.0 -* Elixir >=1.15.0, <1.20 -* Erlang OTP >=24.0.0 (supported: <29) * git * file / libmagic * gcc or clang @@ -14,3 +13,7 @@ * ImageMagick * FFmpeg * exiftool + +!!!info + **Source installs only** + If your operating system repositories don't meet the Elixir/Erlang requirements, check [Installing newer versions of Elixir and Erlang](./installing_newer_elixir_erlang.md). diff --git a/docs/installation/installing_newer_elixir_erlang.md b/docs/installation/installing_newer_elixir_erlang.md new file mode 100644 index 000000000..fd5623785 --- /dev/null +++ b/docs/installation/installing_newer_elixir_erlang.md @@ -0,0 +1,288 @@ +# Installing newer versions of Elixir and Erlang + +This guide is for installing newer versions of Elixir and/or Erlang on your system when installing Pleroma from source and your operating system repositories don't meet the minimum requirements listed below. +This guide assumes you are using Debian or Ubuntu. +**Using the system repositories is recommended if possible.** + +Shell commands prepended with `#` in this page are supposed to be ran with root privileges, commands prepended with `$` are supposed to be ran as the Pleroma user unless noted otherwise. + +!!!warning + If you are, or will be, following the source install guide, make sure to switch to the Pleroma user before running any of the `mix` commands using `sudo -Hu pleroma /bin/bash`. + Not doing so will result in `command not found` errors. + +!!!info + Most of this guide can be used to install Elixir and/or Erlang on operating systems that don't package either one. + Installing Pleroma on such systems is largely untested. + +## Requirements + +{! backend/installation/erlang_elixir_requirements.include !} + +Choose one of the following install methods: + +## Install methods + +* User level: + * mise (Erlang and Elixir install methods are built-in; downloads binaries both for Elixir and Erlang) + * asdf (plugin-based, plugins are shells scripts; builds Erlang from source) + * pkgsrc (for advanced users, harder to install and maintain; builds Elixir and Erlang from source) +* System-wide: + * pkgsrc (for advanced users, harder to install and maintain; builds Elixir and Erlang from source) + +!!!warning + **Ignore if using mise.** + You are about to compile Erlang on your server. + If you are planning to run Pleroma on a VPS virtual machine, make sure you have enough disk space and system resources available. + At least 2GB of RAM and 8GB of extra free disk space is required to continue in this guide. + If your system does not meet these requirements, use [OTP install](./otp_en.md). + **This will take a considerable amount of time.** + +!!!warning + Before proceeding, stop Pleroma if already running and uninstall both Elixir and Erlang. + Keeping Elixir will likely result in a non-functional Elixir install and keeping Erlang can result in various failures to compile Pleroma and its dependencies. + +## mise + +To start, create the Pleroma user according to the [source install guide](./debian_based_en.md#install-pleromabe) and switch to the user using `sudo -Hu pleroma /bin/bash`. +Then follow the install steps from mise documentation and install it for the user Pleroma: [https://mise.jdx.dev/getting-started.html](https://mise.jdx.dev/getting-started.html) + +Add the following to activate mise in the Pleroma user's shell configuration (`.bashrc` for bash): +```sh +# Modify to match the mise installation location +eval "$($HOME/.local/bin/mise activate bash)" +``` + +Source new profile settings: +```sh +$ source ~/.bashrc +``` + +If installing Pleroma, follow the [Pleroma source installation instructions](./debian_based_en.md) up to the point before downloading mix dependencies for Pleroma, ignoring the instructions to download Elixir/Erlang. + +Install Erlang (replace `` with a supported release meeting Pleroma's requirements, OTP 27 is recommended): +```sh +$ mise install erlang@ +``` + +!!!info + To get a list of available versions, use `mise ls-remote `. + +Then run the following in the Pleroma source code repository: +```sh +$ mise use erlang@ +``` + +Install Elixir (replace `` with a supported release and `` with the mise-installed Erlang/OTP version, Elixir 1.18 is recommended): +```sh +$ mise install elixir@-otp- +``` + +Then run the following in the Pleroma source code directory: +```sh +$ mise use elixir@ +``` + +If installing Pleroma, continue with the source install guide up to the point of installing the systemd Pleroma service. +Don't attempt to start the Pleroma service yet. + +Create a `pleroma.sh` startup script owned by the Pleroma user in Pleroma user's home directory: +```sh +#!/bin/bash +# Modify to match the mise installation location +eval "$($HOME/.local/bin/mise activate bash)" + +exec mix phx.server +``` + +Make the startup script executable: +```sh +chmod u+x pleroma.sh +``` + +Override the Pleroma service file to point to the new start up script, run `# systemctl edit pleroma` and add the following: +```ini +[Service] +ExecStart= +ExecStart=/var/lib/pleroma/pleroma.sh +``` + +You can now start the Pleroma service. +If you are installing Pleroma, continue with creating your first user according to the install guide. + +## asdf + +To start, create the Pleroma user according to the [source install guide](./debian_based_en.md#install-pleromabe) and switch to the user using `sudo -Hu pleroma /bin/bash`. +Then follow the install and configure steps from asdf documentation and install it for the user Pleroma: [https://asdf-vm.com/guide/getting-started.html](https://asdf-vm.com/guide/getting-started.html) + +Install dependencies: +``` +# apt install build-essential libssl-dev libncurses-dev git unzip +``` + +Add Erlang autotools configure options to Pleroma user's shell config (`.bashrc` for bash): +```sh +export KERL_CONFIGURE_OPTIONS="--without-javac --without-odbc --without-wx --without-ssh" +``` + +Source new profile settings: +```sh +$ source ~/.bashrc +``` + +Install the Erlang plugin: +```sh +$ asdf plugin add erlang https://github.com/asdf-vm/asdf-erlang.git +``` + +Build and install Erlang (replace `` with a supported release meeting Pleroma's requirements, OTP 27 is recommended): +```sh +$ asdf install erlang +``` + +!!!info + To get a list of available versions, use `asdf list all `. + +Install the Elixir plugin: +```sh +$ asdf plugin add elixir https://github.com/asdf-vm/asdf-elixir.git +``` + +Install Elixir (replace `` with a supported release and `` with the asdf-installed Erlang/OTP version, Elixir 1.18 is recommended): +```sh +$ asdf install elixir -otp- +``` + +If installing Pleroma, follow the [Pleroma source installation instructions](./debian_based_en.md) up to the point before downloading mix dependencies for Pleroma, ignoring the instructions to download Elixir/Erlang. + +Then run the following in the Pleroma source code directory: +```sh +$ asdf set erlang +$ asdf set elixir +``` + +If installing Pleroma, continue with the source install guide up to the point of installing the systemd Pleroma service. +Don't attempt to start the Pleroma service yet. + +Create a `pleroma.sh` startup script owned by the Pleroma user in Pleroma user's home directory: +```sh +#!/bin/sh +# Modify to match your .bashrc settings used when installing asdf +export ASDF_DATA_DIR="/your/custom/data/dir" +export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH" + +exec mix phx.server +``` + +Make the startup script executable: +```sh +chmod u+x pleroma.sh +``` + +Override the Pleroma service file to point to the new start up script, run `# systemctl edit pleroma` and add the following: +```ini +[Service] +ExecStart= +ExecStart=/var/lib/pleroma/pleroma.sh +``` + +You can now start the Pleroma service. +If you are installing Pleroma, continue with creating your first user according to the install guide. + +## pkgsrc + +pkgsrc is NetBSD's portable package building framework also supporting Linux. +Its use is discouraged for novice users as it is harder to maintain and keep up-to-date compared to other options in this guide. + +Before installing pkgsrc, choose which install method (tarball or CVS) you want to use. +Both update differently and have their caveats, check NetBSD documentation for more info: [https://www.netbsd.org/docs/pkgsrc/getting.html#uptodate](https://www.netbsd.org/docs/pkgsrc/getting.html#uptodate) +Using the stable branch is recommended. + +!!!warning + For CVS install, `cvs` might not be installed on your system, in which case it can be installed with `# apt install cvs`. + +pkgsrc supports both user-level and system-wide package installation, hence why most commands below don't have a `#`/`$` prepended to them. +For user-level installs, use the Pleroma user created in the [source install guide](./debian_based_en.md#install-pleromabe). +To start, follow the `quickstart -> install source packages` portion of the guide to acquire pkgsrc: [https://pkgsrc.org](https://pkgsrc.org) + +### Bootstrap + +Install build dependencies for bootstrap: +``` +# apt install build-essential +``` + +For user-level installation run: +```sh +$ cd pkgsrc/bootstrap +$ ./bootstrap --prefer-pkgsrc yes --unprivileged --make-jobs +``` + +For system-wide installation run: +``` +# cd pkgsrc/bootstrap +# ./bootstrap --prefer-pkgsrc yes --make-jobs +``` + +!!!info + For more bootstrap options, run `./bootstrap --help` + +Add pgksrc packages to `$PATH` in shell configuration (`.bashrc` for bash), default prefix is `$HOME/pkg` for user-level install and `/usr/pkg` for system-wide install: +```sh +export PATH="$PATH:/bin" +``` + +Source new profile settings: +```sh +source ~/.bashrc +``` + +!!!info + For system-wide installs, both the root user and Pleroma user need to have the `PATH` set accordingly. + +### Package installation + +Erlang: +```sh +cd pkgsrc/lang/erlang +bmake install clean +``` + +Elixir: +```sh +cd ../elixir +bmake install clean +``` + +### Pleroma startup script + +If installing Pleroma, first follow the [Pleroma source installation instructions](./debian_based_en.md) up to the point of installing the systemd Pleroma service, ignoring the instruction to install Elixir/Erlang. Don't attempt to start the service yet. + +Create a `pleroma.sh` startup script owned by the Pleroma user in Pleroma user's home directory: +```sh +#!/bin/sh +# Modify to match your .bashrc settings used when bootsrapping pkgsrc +export PATH="$PATH:/bin" + +exec mix phx.server +``` + +Make the startup script executable: +```sh +chmod u+x pleroma.sh +``` + +Override the Pleroma service file to point to the new start up script, run `# systemctl edit pleroma` and add the following: +```ini +[Service] +ExecStart= +ExecStart=/var/lib/pleroma/pleroma.sh +``` + +You can now start the Pleroma service. +If you are installing Pleroma, continue with creating your first user according to the install guide. + +## Questions + +Questions about the installation or didn’t it work as it should be, ask in [#pleroma:libera.chat](https://matrix.to/#/#pleroma:libera.chat) via Matrix or **#pleroma** on **libera.chat** via IRC. + + From 775ae5d50493540d2b16f20428a9bed416400eff Mon Sep 17 00:00:00 2001 From: Phantasm Date: Thu, 24 Sep 2026 20:01:06 +0200 Subject: [PATCH 12/19] Docs New Elixir/Erlang versions install: Add maintenance chapter --- .../installing_newer_elixir_erlang.md | 22 ++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/installation/installing_newer_elixir_erlang.md b/docs/installation/installing_newer_elixir_erlang.md index fd5623785..6b7e145ed 100644 --- a/docs/installation/installing_newer_elixir_erlang.md +++ b/docs/installation/installing_newer_elixir_erlang.md @@ -281,8 +281,28 @@ ExecStart=/var/lib/pleroma/pleroma.sh You can now start the Pleroma service. If you are installing Pleroma, continue with creating your first user according to the install guide. +## Maintenance + +Since Elixir and Erlang is no longer managed by the system package manager after following this guide, it is recommended to periodically check their respective websites/repositories for newer versions with security bug fixes. +When updating Elixir, Erlang or both, stop Pleroma before proceeding with the update. + +Pleroma will likely need to be recompiled after the update by running the following command in the Pleroma source code directory as the Pleroma user: +```sh +MIX_ENV=prod mix compile +``` + +If Pleroma fails to compile or start after upgrading Elixir/Erlang, run the following as a troubleshooting step in the Pleroma source code directory as the Pleroma user: +```sh +mix clean +mix deps.clean --all +mix deps.get +MIX_ENV=prod mix compile +``` + +Then try to start Pleroma again. If that doesn't help, join the Matrix room or IRC channel mentioned below, or make an issue on [git.pleroma.social/pleroma/pleroma](https://git.pleroma.social/pleroma/pleroma/issues/new/choose) explaining the problem. + ## Questions -Questions about the installation or didn’t it work as it should be, ask in [#pleroma:libera.chat](https://matrix.to/#/#pleroma:libera.chat) via Matrix or **#pleroma** on **libera.chat** via IRC. +Questions about the guide or it didn’t work as it should, ask in [#pleroma:libera.chat](https://matrix.to/#/#pleroma:libera.chat) via Matrix or **#pleroma** on **libera.chat** via IRC. From 0061f62355145e764ec539424541a2f2386aac5d Mon Sep 17 00:00:00 2001 From: Phantasm Date: Thu, 24 Sep 2026 20:06:42 +0200 Subject: [PATCH 13/19] Docs Newer Elixir/Erlang guide: Recommend upgrading OS release instead --- docs/installation/installing_newer_elixir_erlang.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/installation/installing_newer_elixir_erlang.md b/docs/installation/installing_newer_elixir_erlang.md index 6b7e145ed..8c475e513 100644 --- a/docs/installation/installing_newer_elixir_erlang.md +++ b/docs/installation/installing_newer_elixir_erlang.md @@ -3,6 +3,7 @@ This guide is for installing newer versions of Elixir and/or Erlang on your system when installing Pleroma from source and your operating system repositories don't meet the minimum requirements listed below. This guide assumes you are using Debian or Ubuntu. **Using the system repositories is recommended if possible.** +**If a newer release of your operating system would meet the requirements, consider upgrading instead.** Shell commands prepended with `#` in this page are supposed to be ran with root privileges, commands prepended with `$` are supposed to be ran as the Pleroma user unless noted otherwise. From 62b6a24d5dcc9a371bb4881d88e7d2b636e79c22 Mon Sep 17 00:00:00 2001 From: Phantasm Date: Thu, 24 Sep 2026 20:08:58 +0200 Subject: [PATCH 14/19] Docs: move paragraph --- docs/installation/installing_newer_elixir_erlang.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/installation/installing_newer_elixir_erlang.md b/docs/installation/installing_newer_elixir_erlang.md index 8c475e513..4771f7507 100644 --- a/docs/installation/installing_newer_elixir_erlang.md +++ b/docs/installation/installing_newer_elixir_erlang.md @@ -19,10 +19,10 @@ Shell commands prepended with `#` in this page are supposed to be ran with root {! backend/installation/erlang_elixir_requirements.include !} -Choose one of the following install methods: - ## Install methods +Choose one of the following install methods: + * User level: * mise (Erlang and Elixir install methods are built-in; downloads binaries both for Elixir and Erlang) * asdf (plugin-based, plugins are shells scripts; builds Erlang from source) From 4515f9139c64d04eef57ece6783b24f8547d97e6 Mon Sep 17 00:00:00 2001 From: Phantasm Date: Tue, 29 Sep 2026 10:27:11 +0200 Subject: [PATCH 15/19] Docs OpenBSD: Bump recommended datasize login.conf limit Under OpenBSD datasize not only includes allocated memory using malloc, but also anonymous memory mapped via mmap. --- changelog.d/openbsd-datasize-bump.change | 1 + docs/installation/openbsd_en.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelog.d/openbsd-datasize-bump.change diff --git a/changelog.d/openbsd-datasize-bump.change b/changelog.d/openbsd-datasize-bump.change new file mode 100644 index 000000000..9085cc43a --- /dev/null +++ b/changelog.d/openbsd-datasize-bump.change @@ -0,0 +1 @@ +Docs OpenBSD: Increased recommended `datasize` from 1536M to 4096M to avoid Pleroma crashes diff --git a/docs/installation/openbsd_en.md b/docs/installation/openbsd_en.md index 1de016cdd..4e2f43f85 100644 --- a/docs/installation/openbsd_en.md +++ b/docs/installation/openbsd_en.md @@ -67,7 +67,7 @@ Pleroma will be run by a dedicated \_pleroma user. Before creating it, insert th ``` pleroma:\ - :datasize=1536M:\ + :datasize=4096M:\ :openfiles-max=4096:\ :openfiles-cur=1024:\ :setenv=LC_ALL=en_US.UTF-8,VIX_COMPILATION_MODE=PLATFORM_PROVIDED_LIBVIPS,MIX_ENV=prod:\ From 62d4258d7994e8ebdffb8befea290cc71082906d Mon Sep 17 00:00:00 2001 From: Phantasm Date: Tue, 29 Sep 2026 10:41:13 +0200 Subject: [PATCH 16/19] Docs OpenBSD: Mention running cap_mkdb after making new login class --- docs/installation/openbsd_en.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/installation/openbsd_en.md b/docs/installation/openbsd_en.md index 4e2f43f85..82d137e96 100644 --- a/docs/installation/openbsd_en.md +++ b/docs/installation/openbsd_en.md @@ -74,6 +74,12 @@ pleroma:\ :tc=daemon: ``` +Then run: + +``` +# cap_mkdb /etc/login.conf +``` + This creates a "pleroma" login class and sets higher values than default for datasize and openfiles (see [login.conf(5)](https://man.openbsd.org/login.conf)), this is required to avoid having Pleroma crash some time after starting. Create the \_pleroma user, assign it the pleroma login class and create its home directory (/home/\_pleroma/): From 9c76e0686a017ba465a5b61ce18447a04f517dc9 Mon Sep 17 00:00:00 2001 From: Phantasm Date: Wed, 30 Sep 2026 14:42:10 +0200 Subject: [PATCH 17/19] Deps: Bump captcha version Fixes build on OpenBSD and FreeBSD --- changelog.d/captcha-ver-bump.fix | 1 + mix.exs | 2 +- mix.lock | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 changelog.d/captcha-ver-bump.fix diff --git a/changelog.d/captcha-ver-bump.fix b/changelog.d/captcha-ver-bump.fix new file mode 100644 index 000000000..8e5ea0e9c --- /dev/null +++ b/changelog.d/captcha-ver-bump.fix @@ -0,0 +1 @@ +Updated the captcha package to fix compilation failure on BSD-based systems diff --git a/mix.exs b/mix.exs index 140aafb98..3598a4f53 100644 --- a/mix.exs +++ b/mix.exs @@ -198,7 +198,7 @@ defmodule Pleroma.Mixfile do {:concurrent_limiter, "~> 0.1.1"}, {:remote_ip, "~> 1.2.0"}, {:inet_cidr, "~> 1.0"}, - {:captcha, "~> 1.0.3", hex: :pleroma_captcha}, + {:captcha, "~> 1.0.4", hex: :pleroma_captcha}, {:restarter, path: "./restarter"}, {:majic, "~> 1.2"}, {:open_api_spex, "~> 3.22"}, diff --git a/mix.lock b/mix.lock index bca6f777b..369365cdc 100644 --- a/mix.lock +++ b/mix.lock @@ -10,7 +10,7 @@ "bunt": {:hex, :bunt, "1.0.0", "081c2c665f086849e6d57900292b3a161727ab40431219529f13c4ddcf3e7a44", [:mix], [], "hexpm", "dc5f86aa08a5f6fa6b8096f0735c4e76d54ae5c9fa2c143e5a1fc7c1cd9bb6b5"}, "cachex": {:hex, :cachex, "3.6.0", "14a1bfbeee060dd9bec25a5b6f4e4691e3670ebda28c8ba2884b12fe30b36bf8", [:mix], [{:eternal, "~> 1.2", [hex: :eternal, repo: "hexpm", optional: false]}, {:jumper, "~> 1.0", [hex: :jumper, repo: "hexpm", optional: false]}, {:sleeplocks, "~> 1.1", [hex: :sleeplocks, repo: "hexpm", optional: false]}, {:unsafe, "~> 1.0", [hex: :unsafe, repo: "hexpm", optional: false]}], "hexpm", "ebf24e373883bc8e0c8d894a63bbe102ae13d918f790121f5cfe6e485cc8e2e2"}, "calendar": {:hex, :calendar, "1.0.0", "f52073a708528482ec33d0a171954ca610fe2bd28f1e871f247dc7f1565fa807", [:mix], [{:tzdata, "~> 0.1.201603 or ~> 0.5.20 or ~> 1.0", [hex: :tzdata, repo: "hexpm", optional: false]}], "hexpm", "990e9581920c82912a5ee50e62ff5ef96da6b15949a2ee4734f935fdef0f0a6f"}, - "captcha": {:hex, :pleroma_captcha, "1.0.3", "6cc1440e91a092653fe909f028cc4c5d83ea858b1439e3b9a85e446382e2b9a3", [:make, :mix], [], "hexpm", "477f62c1a845a9458c546658223295f958f98136acef89c05beb278b1b6f4a14"}, + "captcha": {:hex, :pleroma_captcha, "1.0.4", "6e28ef98660981daeb4aee5043551d921b0094ec5bdeb4daf2f01858e14e9d2d", [:make, :mix], [], "hexpm", "aee86d4da3522ef39ba814e6954c4ebe692e72664efcb8fa5819b1335999b577"}, "castore": {:hex, :castore, "1.0.15", "8aa930c890fe18b6fe0a0cff27b27d0d4d231867897bd23ea772dee561f032a3", [:mix], [], "hexpm", "96ce4c69d7d5d7a0761420ef743e2f4096253931a3ba69e5ff8ef1844fe446d3"}, "cc_precompiler": {:hex, :cc_precompiler, "0.1.11", "8c844d0b9fb98a3edea067f94f616b3f6b29b959b6b3bf25fee94ffe34364768", [:mix], [{:elixir_make, "~> 0.7", [hex: :elixir_make, repo: "hexpm", optional: false]}], "hexpm", "3427232caf0835f94680e5bcf082408a70b48ad68a5f5c0b02a3bea9f3a075b9"}, "certifi": {:hex, :certifi, "2.12.0", "2d1cca2ec95f59643862af91f001478c9863c2ac9cb6e2f89780bfd8de987329", [:rebar3], [], "hexpm", "ee68d85df22e554040cdb4be100f33873ac6051387baf6a8f6ce82272340ff1c"}, From 1659fd99d34ff55d51bdbdaa3645ce36cf377478 Mon Sep 17 00:00:00 2001 From: Phantasm Date: Sat, 3 Oct 2026 23:40:07 +0200 Subject: [PATCH 18/19] Docs: Add missing curl dependency for asdf --- changelog.d/fixup-new-elixir-erlang-docs.skip | 0 docs/installation/installing_newer_elixir_erlang.md | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 changelog.d/fixup-new-elixir-erlang-docs.skip diff --git a/changelog.d/fixup-new-elixir-erlang-docs.skip b/changelog.d/fixup-new-elixir-erlang-docs.skip new file mode 100644 index 000000000..e69de29bb diff --git a/docs/installation/installing_newer_elixir_erlang.md b/docs/installation/installing_newer_elixir_erlang.md index 4771f7507..0d06d2fba 100644 --- a/docs/installation/installing_newer_elixir_erlang.md +++ b/docs/installation/installing_newer_elixir_erlang.md @@ -117,7 +117,7 @@ Then follow the install and configure steps from asdf documentation and install Install dependencies: ``` -# apt install build-essential libssl-dev libncurses-dev git unzip +# apt install build-essential libssl-dev libncurses-dev git unzip curl ``` Add Erlang autotools configure options to Pleroma user's shell config (`.bashrc` for bash): From 0421e8b2e373f5a5fc40f889c18af2a7e45a02ec Mon Sep 17 00:00:00 2001 From: Phantasm Date: Sun, 4 Oct 2026 20:23:16 +0200 Subject: [PATCH 19/19] Docs New Elixir/Erlang: Clarify that mise builds Erlang on Debian --- .../installing_newer_elixir_erlang.md | 32 ++++++++++++++++--- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/docs/installation/installing_newer_elixir_erlang.md b/docs/installation/installing_newer_elixir_erlang.md index 0d06d2fba..0220996d8 100644 --- a/docs/installation/installing_newer_elixir_erlang.md +++ b/docs/installation/installing_newer_elixir_erlang.md @@ -24,14 +24,16 @@ Shell commands prepended with `#` in this page are supposed to be ran with root Choose one of the following install methods: * User level: - * mise (Erlang and Elixir install methods are built-in; downloads binaries both for Elixir and Erlang) + * mise (Erlang and Elixir install methods are built-in[^1]) * asdf (plugin-based, plugins are shells scripts; builds Erlang from source) * pkgsrc (for advanced users, harder to install and maintain; builds Elixir and Erlang from source) * System-wide: * pkgsrc (for advanced users, harder to install and maintain; builds Elixir and Erlang from source) +[^1]: On Ubuntu downloads binaries both for Elixir and Erlang. On Debian builds Erlang from source and downloads binaries for Elixir. + !!!warning - **Ignore if using mise.** + **Ignore if using mise on Ubuntu.** You are about to compile Erlang on your server. If you are planning to run Pleroma on a VPS virtual machine, make sure you have enough disk space and system resources available. At least 2GB of RAM and 8GB of extra free disk space is required to continue in this guide. @@ -44,8 +46,30 @@ Choose one of the following install methods: ## mise -To start, create the Pleroma user according to the [source install guide](./debian_based_en.md#install-pleromabe) and switch to the user using `sudo -Hu pleroma /bin/bash`. -Then follow the install steps from mise documentation and install it for the user Pleroma: [https://mise.jdx.dev/getting-started.html](https://mise.jdx.dev/getting-started.html) +To start, create the Pleroma user according to the [source install guide](./debian_based_en.md#install-pleromabe). + +### Debian-only preparation + +If you are using Ubuntu, skip to the [next section](./installing_newer_elixir_erlang.md#elixirerlang-installation). + +Install dependencies: +``` +# apt install build-essential libssl-dev libncurses-dev git unzip +``` + +Add Erlang autotools configure options to Pleroma user's shell config (`.bashrc` for bash): +```sh +export KERL_CONFIGURE_OPTIONS="--without-javac --without-odbc --without-wx --without-ssh" +``` + +### Elixir/Erlang installation + +Install curl (for the mise installer): +``` +# apt install curl +``` + +Switch to the Pleroma user using `sudo -Hu pleroma /bin/bash` and follow the install steps from mise documentation and install it for the user Pleroma: [https://mise.jdx.dev/getting-started.html](https://mise.jdx.dev/getting-started.html) Add the following to activate mise in the Pleroma user's shell configuration (`.bashrc` for bash): ```sh