diff --git a/.woodpecker/docs.yaml b/.woodpecker/docs.yaml new file mode 100644 index 000000000..2a6023abd --- /dev/null +++ b/.woodpecker/docs.yaml @@ -0,0 +1,45 @@ +when: + - event: push + branch: ${CI_REPO_DEFAULT_BRANCH} + path: [ "docs/**" ] + - event: tag + - event: manual + evaluate: 'CI_COMMIT_BRANCH == "stable" || CI_COMMIT_BRANCH == CI_REPO_DEFAULT_BRANCH' + +labels: + platform: linux/amd64 + +skip_clone: true + +variables: + trigger_settings: &trigger_settings + 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: + 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 diff --git a/.woodpecker/spec-build.yaml b/.woodpecker/spec-build.yaml new file mode 100644 index 000000000..0024a62f1 --- /dev/null +++ b/.woodpecker/spec-build.yaml @@ -0,0 +1,103 @@ +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 + 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 + user: + from_secret: pleroma-ci-user + 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: + 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 + 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 + - | + 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 + settings: + <<: *artifacts_uploader_settings + package_version: ${CI_COMMIT_SHA} + + 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: + - trigger-deploy-stable.params + + trigger-deploy-develop: + when: + - event: push + - event: manual + branch: ${CI_REPO_DEFAULT_BRANCH} + image: *trigger_image + settings: + <<: *trigger_settings + params: + - trigger-deploy-develop.params 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/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/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/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/changelog.d/woodpecker-ci-docs.skip b/changelog.d/woodpecker-ci-docs.skip new file mode 100644 index 000000000..e69de29bb diff --git a/changelog.d/woodpecker-trigger-params.skip b/changelog.d/woodpecker-trigger-params.skip new file mode 100644 index 000000000..e69de29bb 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 3027e9025..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.17.0, <1.20 -* Erlang OTP >=27.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..0220996d8 --- /dev/null +++ b/docs/installation/installing_newer_elixir_erlang.md @@ -0,0 +1,333 @@ +# 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.** +**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. + +!!!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 !} + +## Install methods + +Choose one of the following install methods: + +* User level: + * 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 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. + 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). + +### 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 +# 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 curl +``` + +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. + +## 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 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. + + diff --git a/docs/installation/openbsd_en.md b/docs/installation/openbsd_en.md index 1de016cdd..82d137e96 100644 --- a/docs/installation/openbsd_en.md +++ b/docs/installation/openbsd_en.md @@ -67,13 +67,19 @@ 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:\ :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/): diff --git a/mix.exs b/mix.exs index d323d478f..3c247cc0e 100644 --- a/mix.exs +++ b/mix.exs @@ -200,7 +200,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 9b3b1714a..ba7ef0c45 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.22", "a01978e6a5d42fa3a34143630588f92036e7d90e2309ecdd466722d1279a2213", [:mix], [], "hexpm", "c2a4d42723b4affbc1c3e15d8f6df3f7d8f1f627c84de643383634cce58493d5"}, "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.17.0", "835748414307e15e05b17d0e518190228ce648b08d569a5cc93a85a40f3e5c9b", [:rebar3], [], "hexpm", "8122798a17f0293c80daada25d0f81c7f4d708c73fef782c7c9b1950e26e4d21"},