From 43dfa58ebda407a0813d398bee8d0ae3e5c9fd5b Mon Sep 17 00:00:00 2001 From: Claudio Maradonna Date: Mon, 11 Apr 2022 15:10:01 +0200 Subject: added tests for ipfs uploader. adapted changelog.md accordingly. improved ipfs uploader with external suggestions fix lint description.exs --- docs/configuration/cheatsheet.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'docs') diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index 74642397b..7e1f9c934 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -614,6 +614,19 @@ config :ex_aws, :s3, host: "s3.eu-central-1.amazonaws.com" ``` +#### Pleroma.Uploaders.IPFS + +* `post_gateway_url`: URL with port of POST Gateway (unauthenticated) +* `get_gateway_url`: URL of public GET Gateway + +Example: + +```elixir +config :pleroma, Pleroma.Uploaders.IPFS, + post_gateway_url: "http://localhost:5001", + get_gateway_url: "http://<%= cid %>.ipfs.mydomain.com" +``` + ### Upload filters #### Pleroma.Upload.Filter.AnonymizeFilename -- cgit v1.2.3 From 44659ecd65fb2251f9130fcecf1732b8931104c1 Mon Sep 17 00:00:00 2001 From: Claudio Maradonna Date: Sat, 16 Apr 2022 09:38:49 +0200 Subject: ipfs: revert to String.replace for cid placeholder ipfs: fix lint --- docs/configuration/cheatsheet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index 7e1f9c934..d35b33574 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -624,7 +624,7 @@ Example: ```elixir config :pleroma, Pleroma.Uploaders.IPFS, post_gateway_url: "http://localhost:5001", - get_gateway_url: "http://<%= cid %>.ipfs.mydomain.com" + get_gateway_url: "http://{CID}.ipfs.mydomain.com" ``` ### Upload filters -- cgit v1.2.3 From 07ccab9766a6289326676a4814537564f25f35fa Mon Sep 17 00:00:00 2001 From: Ekaterina Vaartis Date: Mon, 23 Aug 2021 20:27:16 +0300 Subject: Add search/meilisearch documentation --- docs/configuration/search.md | 99 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 docs/configuration/search.md (limited to 'docs') diff --git a/docs/configuration/search.md b/docs/configuration/search.md new file mode 100644 index 000000000..14ec2bc63 --- /dev/null +++ b/docs/configuration/search.md @@ -0,0 +1,99 @@ +# Configuring search + +{! backend/administration/CLI_tasks/general_cli_task_info.include !} + +## Built-in search + +To use built-in search that has no external dependencies, set the search module to `Pleroma.Activity`: + +> config :pleroma, Pleroma.Search, module: Pleroma.Activity + +While it has no external dependencies, it has problems with performance and relevancy. + +## Meilisearch + +To use [meilisearch](https://www.meilisearch.com/), set the search module to `Pleroma.Search.Meilisearch`: + +> config :pleroma, Pleroma.Search, module: Pleroma.Search.Meilisearch + +You then need to set the address of the meilisearch instance, and optionally the private key for authentication. + +> config :pleroma, Pleroma.Search.Meilisearch, +> url: "http://127.0.0.1:7700/", +> private_key: "private key" + +Information about setting up meilisearch can be found in the +[official documentation](https://docs.meilisearch.com/learn/getting_started/installation.html). +You probably want to start it with `MEILI_NO_ANALYTICS=true` and `MEILI_NO_CENTRY=true` environment variables, +to disable analytics. + +### Private key authentication (optional) + +To set the private key, use the `MEILI_MASTER_KEY` environment variable when starting. After setting the _master key_, +you have to get the _private key_, which is actually used for authentication. + +=== "OTP" + ```sh + ./bin/pleroma_ctl search.meilisearch show-private-key + ``` + +=== "From Source" + ```sh + mix pleroma.search.meilisearch show-private-key + ``` + +This is the key you actually put into your configuration file. + +### Initial indexing + +After setting up the configuration, you'll want to index all of your already existsing posts. Only public posts are indexed. You'll only +have to do it one time, but it might take a while, depending on the amount of posts your instance has seen. This is also a fairly RAM +consuming process for `meilisearch`, and it will take a lot of RAM when running if you have a lot of posts (seems to be around 5G for ~1.2 +million posts while idle and up to 7G while indexing initially, but your experience may be different). + +To start te initial indexing, run the `index` command: + +=== "OTP" + ```sh + ./bin/pleroma_ctl search.meilisearch index + ``` + +=== "From Source" + ```sh + mix pleroma.search.meilisearch index + ``` + +This will show you the total amount of posts to index, and then show you the amount of posts indexed currently, until the numbers eventually +become the same. The posts are indexed in big batches and meilisearch will take some time to actually index them, even after you have +inserted all the posts into it. Depending on the amount of posts, this may be as long as several hours. To get information about the status +of indexing and how many posts have actually been indexed, use the `stats` command: + +=== "OTP" + ```sh + ./bin/pleroma_ctl search.meilisearch stats + ``` + +=== "From Source" + ```sh + mix pleroma.search.meilisearch stats + ``` + +### Clearing the index + +In case you need to clear the index (for example, to re-index from scratch, if that needs to happen for some reason), you can +use the `clear` command: + +=== "OTP" + ```sh + ./bin/pleroma_ctl search.meilisearch clear + ``` + +=== "From Source" + ```sh + mix pleroma.search.meilisearch clear + ``` + +This will clear **all** the posts from the search index. Note, that deleted posts are also removed from index by the instance itself, so +there is no need to actually clear the whole index, unless you want **all** of it gone. That said, the index does not hold any information +that cannot be re-created from the database, it should also generally be a lot smaller than the size of your database. Still, the size +depends on the amount of text in posts. -- cgit v1.2.3 From c569ad05b3d812c87171e68eac79eec749321033 Mon Sep 17 00:00:00 2001 From: Ekaterina Vaartis Date: Tue, 12 Oct 2021 19:14:39 +0300 Subject: Add more documentation about rum to meilisearch docs --- docs/configuration/search.md | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs') diff --git a/docs/configuration/search.md b/docs/configuration/search.md index 14ec2bc63..e9743f1a4 100644 --- a/docs/configuration/search.md +++ b/docs/configuration/search.md @@ -12,6 +12,15 @@ While it has no external dependencies, it has problems with performance and rele ## Meilisearch +Note that it's quite a bit more memory hungry than PostgreSQL (around 4-5G for ~1.2 million +posts while idle and up to 7G while indexing initially). The disk usage for this additional index is also +around 4 gigabytes. Like [RUM](./cheatsheet.md#rum-indexing-for-full-text-search) indexes, it offers considerably +higher performance and ordering by timestamp in a reasonable amount of time. +Additionally, the search results seem to be more accurate. + +Due to high memory usage, it may be best to set it up on a different machine, if running pleroma on a low-resource +computer, and use private key authentication to secure the remote search instance. + To use [meilisearch](https://www.meilisearch.com/), set the search module to `Pleroma.Search.Meilisearch`: > config :pleroma, Pleroma.Search, module: Pleroma.Search.Meilisearch -- cgit v1.2.3 From 8898b5e927bae27a521e4eadd0faf970ad27c5bc Mon Sep 17 00:00:00 2001 From: Ekaterina Vaartis Date: Sun, 14 Nov 2021 20:15:12 +0300 Subject: Fix a typo in search docs --- docs/configuration/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/configuration/search.md b/docs/configuration/search.md index e9743f1a4..9adc7884f 100644 --- a/docs/configuration/search.md +++ b/docs/configuration/search.md @@ -60,7 +60,7 @@ have to do it one time, but it might take a while, depending on the amount of po consuming process for `meilisearch`, and it will take a lot of RAM when running if you have a lot of posts (seems to be around 5G for ~1.2 million posts while idle and up to 7G while indexing initially, but your experience may be different). -To start te initial indexing, run the `index` command: +To start the initial indexing, run the `index` command: === "OTP" ```sh -- cgit v1.2.3 From a6946048fbe049aa223d094d36eb767739ab5ff2 Mon Sep 17 00:00:00 2001 From: Ekaterina Vaartis Date: Wed, 17 Nov 2021 22:29:49 +0300 Subject: Rename Activity.Search to Search.DatabaseSearch --- docs/configuration/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/configuration/search.md b/docs/configuration/search.md index 9adc7884f..c7e77d9c2 100644 --- a/docs/configuration/search.md +++ b/docs/configuration/search.md @@ -6,7 +6,7 @@ To use built-in search that has no external dependencies, set the search module to `Pleroma.Activity`: -> config :pleroma, Pleroma.Search, module: Pleroma.Activity +> config :pleroma, Pleroma.Search, module: Pleroma.Search.DatabaseSearch While it has no external dependencies, it has problems with performance and relevancy. -- cgit v1.2.3 From 3412713c5b2fd24605b18933ef70de164ee14f2d Mon Sep 17 00:00:00 2001 From: Ekaterina Vaartis Date: Mon, 20 Dec 2021 18:16:33 +0300 Subject: Update search.md documentation with meilisearch indexing steps --- docs/configuration/search.md | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs') diff --git a/docs/configuration/search.md b/docs/configuration/search.md index c7e77d9c2..7dbbd3e17 100644 --- a/docs/configuration/search.md +++ b/docs/configuration/search.md @@ -60,6 +60,15 @@ have to do it one time, but it might take a while, depending on the amount of po consuming process for `meilisearch`, and it will take a lot of RAM when running if you have a lot of posts (seems to be around 5G for ~1.2 million posts while idle and up to 7G while indexing initially, but your experience may be different). +The sequence of actions is as follows: + +1. First, change the configuration to use `Pleroma.Search.Meilisearch` as the search backend +2. Restart your instance, at this point it can be used while the search indexing is running, though search won't return anything +3. Start the initial indexing process (as described below with `index`), + and wait until the task says it sent everything from the database to index +4. Wait until everything is actually indexed (by checking with `stats` as described below), + at this point you don't have to do anything, just wait a while. + To start the initial indexing, run the `index` command: === "OTP" -- cgit v1.2.3 From 4f2637acc6c46ea39ae38e869903e7ffcc38b34d Mon Sep 17 00:00:00 2001 From: Ekaterina Vaartis Date: Mon, 20 Dec 2021 19:27:22 +0300 Subject: Add description for initial_indexing_chunk_size --- docs/configuration/search.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/configuration/search.md b/docs/configuration/search.md index 7dbbd3e17..a785a18ad 100644 --- a/docs/configuration/search.md +++ b/docs/configuration/search.md @@ -25,11 +25,15 @@ To use [meilisearch](https://www.meilisearch.com/), set the search module to `Pl > config :pleroma, Pleroma.Search, module: Pleroma.Search.Meilisearch -You then need to set the address of the meilisearch instance, and optionally the private key for authentication. +You then need to set the address of the meilisearch instance, and optionally the private key for authentication. You might +also want to change the `initial_indexing_chunk_size` to be smaller if you're server is not very powerful, but not higher than `100_000`, +because meilisearch will refuse to process it if it's too big. However, in general you want this to be as big as possible, because meilisearch +indexes faster when it can process many posts in a single batch. > config :pleroma, Pleroma.Search.Meilisearch, > url: "http://127.0.0.1:7700/", -> private_key: "private key" +> private_key: "private key", +> initial_indexing_chunk_size: 100_000 Information about setting up meilisearch can be found in the [official documentation](https://docs.meilisearch.com/learn/getting_started/installation.html). -- cgit v1.2.3 From 1e23f527e3e22108b402552a0766e488048ed3f4 Mon Sep 17 00:00:00 2001 From: Ekaterina Vaartis Date: Tue, 22 Mar 2022 20:29:17 +0300 Subject: Change the meilisearch key auth to conform to 0.25.0 --- docs/configuration/search.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/configuration/search.md b/docs/configuration/search.md index a785a18ad..82217e5ee 100644 --- a/docs/configuration/search.md +++ b/docs/configuration/search.md @@ -47,15 +47,15 @@ you have to get the _private key_, which is actually used for authentication. === "OTP" ```sh - ./bin/pleroma_ctl search.meilisearch show-private-key + ./bin/pleroma_ctl search.meilisearch show-keys ``` === "From Source" ```sh - mix pleroma.search.meilisearch show-private-key + mix pleroma.search.meilisearch show-keys ``` -This is the key you actually put into your configuration file. +You will see a "Default Admin API Key", this is the key you actually put into your configuration file. ### Initial indexing -- cgit v1.2.3 From b150e6f15e0f06c8e23c0ac66aeaf80eb2f8c31a Mon Sep 17 00:00:00 2001 From: Ekaterina Vaartis Date: Wed, 23 Mar 2022 11:36:01 +0300 Subject: Update meilisearch docs --- docs/configuration/search.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/configuration/search.md b/docs/configuration/search.md index 82217e5ee..f131948a7 100644 --- a/docs/configuration/search.md +++ b/docs/configuration/search.md @@ -37,8 +37,10 @@ indexes faster when it can process many posts in a single batch. Information about setting up meilisearch can be found in the [official documentation](https://docs.meilisearch.com/learn/getting_started/installation.html). -You probably want to start it with `MEILI_NO_ANALYTICS=true` and `MEILI_NO_CENTRY=true` environment variables, -to disable analytics. +You probably want to start it with `MEILI_NO_ANALYTICS=true` environment variable to disable analytics. +At least version 0.25.0 is required, but you are strongly adviced to use at least 0.26.0, as it introduces +the `--enable-auto-batching` option which drastically improves performance. Without this option, the search +is hardly usable on a somewhat big instance. ### Private key authentication (optional) -- cgit v1.2.3 From 8e072baed0744c8e4e29f54c608f3f29abb4fba8 Mon Sep 17 00:00:00 2001 From: "Haelwenn (lanodan) Monnier" Date: Sun, 5 Mar 2023 08:41:15 +0100 Subject: docs: Be more explicit about the level of compatibility of OTP releases --- docs/installation/otp_en.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/installation/otp_en.md b/docs/installation/otp_en.md index 8c02201e6..f2812346b 100644 --- a/docs/installation/otp_en.md +++ b/docs/installation/otp_en.md @@ -2,15 +2,16 @@ {! backend/installation/otp_vs_from_source.include !} -This guide covers a installation using an OTP release. To install Pleroma from source, please check out the corresponding guide for your distro. +This guide covers a installation using OTP releases as built by the Pleroma project, it is meant as a fallback to distribution packages/recipes which are the preferred installation method. +To install Pleroma from source, please check out the corresponding guide for your distro. ## Pre-requisites -* A machine running Linux with GNU (e.g. Debian, Ubuntu) or musl (e.g. Alpine) libc and `x86_64`, `aarch64` or `armv7l` CPU, you have root access to. If you are not sure if it's compatible see [Detecting flavour section](#detecting-flavour) below +* A machine you have root access to running Debian GNU/Linux or compatible (eg. Ubuntu), or Alpine on `x86_64`, `aarch64` or `armv7l` CPU. If you are not sure what you are running see [Detecting flavour section](#detecting-flavour) below * A (sub)domain pointed to the machine -You will be running commands as root. If you aren't root already, please elevate your privileges by executing `sudo su`/`su`. +You will be running commands as root. If you aren't root already, please elevate your privileges by executing `sudo -i`/`su`. -While in theory OTP releases are possbile to install on any compatible machine, for the sake of simplicity this guide focuses only on Debian/Ubuntu and Alpine. +Similarly to other binaries, OTP releases tend to be only compatible with the distro they are built on, as such this guide focuses only on Debian/Ubuntu and Alpine. ### Detecting flavour @@ -19,7 +20,7 @@ Paste the following into the shell: arch="$(uname -m)";if [ "$arch" = "x86_64" ];then arch="amd64";elif [ "$arch" = "armv7l" ];then arch="arm";elif [ "$arch" = "aarch64" ];then arch="arm64";else echo "Unsupported arch: $arch">&2;fi;if getconf GNU_LIBC_VERSION>/dev/null;then libc_postfix="";elif [ "$(ldd 2>&1|head -c 9)" = "musl libc" ];then libc_postfix="-musl";elif [ "$(find /lib/libc.musl*|wc -l)" ];then libc_postfix="-musl";else echo "Unsupported libc">&2;fi;echo "$arch$libc_postfix" ``` -If your platform is supported the output will contain the flavour string, you will need it later. If not, this just means that we don't build releases for your platform, you can still try installing from source. +This should give your flavour string. If not this just means that we don't build releases for your platform, you can still try installing from source. ### Installing the required packages -- cgit v1.2.3 From d3b27d45a9115c04d4e469d1a9dc372ff8576d52 Mon Sep 17 00:00:00 2001 From: Ekaterina Vaartis Date: Wed, 29 Mar 2023 23:18:44 +0300 Subject: List installed frontend refs in admin API --- docs/development/API/admin_api.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/development/API/admin_api.md b/docs/development/API/admin_api.md index f6e9f7d2a..7d31ee262 100644 --- a/docs/development/API/admin_api.md +++ b/docs/development/API/admin_api.md @@ -1585,6 +1585,7 @@ Returns the content of the document "build_url": "https://git.pleroma.social/pleroma/fedi-fe/-/jobs/artifacts/${ref}/download?job=build", "git": "https://git.pleroma.social/pleroma/fedi-fe", "installed": true, + "installed_refs": ["master"], "name": "fedi-fe", "ref": "master" }, @@ -1592,6 +1593,7 @@ Returns the content of the document "build_url": "https://git.pleroma.social/lambadalambda/kenoma/-/jobs/artifacts/${ref}/download?job=build", "git": "https://git.pleroma.social/lambadalambda/kenoma", "installed": false, + "installed_refs": [], "name": "kenoma", "ref": "master" } -- cgit v1.2.3 From 81e1d6d9d06225204530d06d549dbd17419a27bb Mon Sep 17 00:00:00 2001 From: AkiraFukushima Date: Sun, 2 Apr 2023 01:02:22 +0900 Subject: Add Fedistar as a desktop client in docs --- docs/clients.md | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs') diff --git a/docs/clients.md b/docs/clients.md index 31d2d27c3..67ef7dd46 100644 --- a/docs/clients.md +++ b/docs/clients.md @@ -23,6 +23,13 @@ Feel free to contact us to be added to this list! - Platforms: Windows, Mac, Linux - Features: MastoAPI, Streaming Ready +### Fedistar +- Homepage: +- Source Code: +- Contact: [@h3poteto@pleroma.io](https://pleroma.io/users/h3poteto) +- Platforms: Windows, Mac, Linux +- Features: MastoAPI, Streaming Ready + ## Handheld ### AndStatus - Homepage: -- cgit v1.2.3 From 17f1b8d13355e40f0d136f9b80876c16c0b67175 Mon Sep 17 00:00:00 2001 From: AkiraFukushima Date: Sun, 2 Apr 2023 01:03:15 +0900 Subject: Remove Roma from docs Because this app is no longer maintained --- docs/clients.md | 6 ------ 1 file changed, 6 deletions(-) (limited to 'docs') diff --git a/docs/clients.md b/docs/clients.md index 67ef7dd46..664955bb5 100644 --- a/docs/clients.md +++ b/docs/clients.md @@ -3,12 +3,6 @@ Note: Additional clients may be working but theses are officially supporting Ple Feel free to contact us to be added to this list! ## Desktop -### Roma for Desktop -- Homepage: -- Source Code: -- Platforms: Windows, Mac, Linux -- Features: MastoAPI, Streaming Ready - ### Social - Source Code: - Contact: [@brainblasted@social.libre.fi](https://social.libre.fi/users/brainblasted) -- cgit v1.2.3 From e5f36f9f8dfbcb718e64a2cd5b174a05b3e35f4d Mon Sep 17 00:00:00 2001 From: AkiraFukushima Date: Sun, 2 Apr 2023 01:07:07 +0900 Subject: Update contact information for Whalebird and Fedistar --- docs/clients.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/clients.md b/docs/clients.md index 664955bb5..ad7eb7807 100644 --- a/docs/clients.md +++ b/docs/clients.md @@ -13,14 +13,14 @@ Feel free to contact us to be added to this list! ### Whalebird - Homepage: - Source Code: -- Contact: [@h3poteto@pleroma.io](https://pleroma.io/users/h3poteto) +- Contact: [@whalebird@pleroma.io](https://pleroma.io/users/whalebird) - Platforms: Windows, Mac, Linux - Features: MastoAPI, Streaming Ready ### Fedistar - Homepage: - Source Code: -- Contact: [@h3poteto@pleroma.io](https://pleroma.io/users/h3poteto) +- Contact: [@fedistar@pleroma.io](https://pleroma.io/users/fedistar) - Platforms: Windows, Mac, Linux - Features: MastoAPI, Streaming Ready -- cgit v1.2.3 From e444832bb5d0a02ca1a0988c3490d72b99758899 Mon Sep 17 00:00:00 2001 From: Duponin Date: Mon, 10 Apr 2023 20:17:30 +0000 Subject: fix OTP install documentation 'su pleroma' will never work if 'pleroma' user has no password, which is better for security purpose. If admin has no 'sudo' binary, I'm expecting them to be skilled enough to make their way on their own. --- docs/installation/otp_en.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/installation/otp_en.md b/docs/installation/otp_en.md index 13f9636f3..e7dec9039 100644 --- a/docs/installation/otp_en.md +++ b/docs/installation/otp_en.md @@ -111,13 +111,13 @@ adduser --system --shell /bin/false --home /opt/pleroma pleroma export FLAVOUR="amd64-musl" # Clone the release build into a temporary directory and unpack it -su pleroma -s $SHELL -lc " +sudo -u pleroma -s $SHELL -lc " curl 'https://git.pleroma.social/api/v4/projects/2/jobs/artifacts/stable/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 " +sudo -u pleroma -s $SHELL -lc " mv /tmp/release/* /opt/pleroma rmdir /tmp/release rm /tmp/pleroma.zip @@ -138,25 +138,25 @@ mkdir -p /etc/pleroma chown -R pleroma /etc/pleroma # Run the config generator -su pleroma -s $SHELL -lc "./bin/pleroma_ctl instance gen --output /etc/pleroma/config.exs --output-psql /tmp/setup_db.psql" +sudo -u pleroma -s $SHELL -lc "./bin/pleroma_ctl instance gen --output /etc/pleroma/config.exs --output-psql /tmp/setup_db.psql" # Create the postgres database -su postgres -s $SHELL -lc "psql -f /tmp/setup_db.psql" +sudo -u postgres -s $SHELL -lc "psql -f /tmp/setup_db.psql" # Create the database schema -su pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate" +sudo -u pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate" # If you have installed RUM indexes uncommend and run -# su pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate --migrations-path priv/repo/optional_migrations/rum_indexing/" +# sudo -u pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate --migrations-path priv/repo/optional_migrations/rum_indexing/" # Start the instance to verify that everything is working as expected -su pleroma -s $SHELL -lc "./bin/pleroma daemon" +sudo -u 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" +sudo -u pleroma -s $SHELL -lc "./bin/pleroma stop" ``` ### Setting up nginx and getting Let's Encrypt SSL certificaties -- cgit v1.2.3 From 7944271c1bdf4a4240b682249c068deb1b2acab0 Mon Sep 17 00:00:00 2001 From: Duponin Date: Sat, 15 Apr 2023 19:03:51 +0000 Subject: Unify install guides using sudo to use `sudo -Hu` --- docs/installation/migrating_from_source_otp_en.md | 8 ++++---- docs/installation/otp_en.md | 14 +++++++------- 2 files changed, 11 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/installation/migrating_from_source_otp_en.md b/docs/installation/migrating_from_source_otp_en.md index d303a6daf..64d335331 100644 --- a/docs/installation/migrating_from_source_otp_en.md +++ b/docs/installation/migrating_from_source_otp_en.md @@ -85,26 +85,26 @@ export FLAVOUR="amd64-musl" # Clone the release build into a temporary directory and unpack it # Replace `stable` with `unstable` if you want to run the unstable branch -su pleroma -s $SHELL -lc " +sudo -Hu pleroma " curl 'https://git.pleroma.social/api/v4/projects/2/jobs/artifacts/stable/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 " +sudo -Hu pleroma " mv /tmp/release/* ~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" +sudo -Hu pleroma "./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" +sudo -Hu pleroma "./bin/pleroma stop" ``` ## Setting up a system service diff --git a/docs/installation/otp_en.md b/docs/installation/otp_en.md index e7dec9039..12078cb20 100644 --- a/docs/installation/otp_en.md +++ b/docs/installation/otp_en.md @@ -111,13 +111,13 @@ adduser --system --shell /bin/false --home /opt/pleroma pleroma export FLAVOUR="amd64-musl" # Clone the release build into a temporary directory and unpack it -sudo -u pleroma -s $SHELL -lc " +sudo -Hu pleroma " curl 'https://git.pleroma.social/api/v4/projects/2/jobs/artifacts/stable/download?job=$FLAVOUR' -o /tmp/pleroma.zip unzip /tmp/pleroma.zip -d /tmp/ " # Move the release to the home directory and delete temporary files -sudo -u pleroma -s $SHELL -lc " +sudo -Hu pleroma " mv /tmp/release/* /opt/pleroma rmdir /tmp/release rm /tmp/pleroma.zip @@ -138,25 +138,25 @@ mkdir -p /etc/pleroma chown -R pleroma /etc/pleroma # Run the config generator -sudo -u pleroma -s $SHELL -lc "./bin/pleroma_ctl instance gen --output /etc/pleroma/config.exs --output-psql /tmp/setup_db.psql" +sudo -Hu pleroma "./bin/pleroma_ctl instance gen --output /etc/pleroma/config.exs --output-psql /tmp/setup_db.psql" # Create the postgres database sudo -u postgres -s $SHELL -lc "psql -f /tmp/setup_db.psql" # Create the database schema -sudo -u pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate" +sudo -Hu pleroma "./bin/pleroma_ctl migrate" # If you have installed RUM indexes uncommend and run -# sudo -u pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate --migrations-path priv/repo/optional_migrations/rum_indexing/" +# sudo -Hu pleroma "./bin/pleroma_ctl migrate --migrations-path priv/repo/optional_migrations/rum_indexing/" # Start the instance to verify that everything is working as expected -sudo -u pleroma -s $SHELL -lc "./bin/pleroma daemon" +sudo -Hu pleroma "./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 -sudo -u pleroma -s $SHELL -lc "./bin/pleroma stop" +sudo -Hu pleroma "./bin/pleroma stop" ``` ### Setting up nginx and getting Let's Encrypt SSL certificaties -- cgit v1.2.3 From 0231a09310895bd2af24eff221de97eb8c92307e Mon Sep 17 00:00:00 2001 From: duponin Date: Sun, 16 Apr 2023 15:50:32 +0200 Subject: Remove SSH/BBS feature from core And link to sshocial, the replacement client for this removed feature --- docs/configuration/cheatsheet.md | 17 ++--------------- 1 file changed, 2 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index bbdf30a0f..70abe3e0c 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -873,21 +873,8 @@ This will probably take a long time. ### BBS / SSH access -To enable simple command line interface accessible over ssh, add a setting like this to your configuration file: - -```exs -app_dir = File.cwd! -priv_dir = Path.join([app_dir, "priv/ssh_keys"]) - -config :esshd, - enabled: true, - priv_dir: priv_dir, - handler: "Pleroma.BBS.Handler", - port: 10_022, - password_authenticator: "Pleroma.BBS.Authenticator" -``` - -Feel free to adjust the priv_dir and port number. Then you will have to create the key for the keys (in the example `priv/ssh_keys`) and create the host keys with `ssh-keygen -m PEM -N "" -b 2048 -t rsa -f ssh_host_rsa_key`. After restarting, you should be able to connect to your Pleroma instance with `ssh username@server -p $PORT` +This feature has been removed from Pleroma core. +However, a client has been made and is available at https://git.pleroma.social/Duponin/sshocial. ### :gopher * `enabled`: Enables the gopher interface -- cgit v1.2.3 From f970091c6a58d06a42594e2c4a0baa5a86617652 Mon Sep 17 00:00:00 2001 From: tusooa Date: Fri, 26 May 2023 17:17:13 -0400 Subject: Add instructions to serve media on another domain --- docs/configuration/hardening.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'docs') diff --git a/docs/configuration/hardening.md b/docs/configuration/hardening.md index d3bfc4e4a..4f40873e6 100644 --- a/docs/configuration/hardening.md +++ b/docs/configuration/hardening.md @@ -62,6 +62,20 @@ An additional “Expect-CT” header will be sent with the configured `ct_max_ag If you click on a link, your browser’s request to the other site will include from where it is coming from. The “Referrer policy” header tells the browser how and if it should send this information. (see [Referrer policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy)) +### Uploaded media and media proxy + +It is STRONGLY RECOMMENDED to serve both the locally-uploaded media and the media proxy from another domain than the domain that Pleroma runs on, if applicable. + +```elixir +config :pleroma, :media_proxy, + base_url: "https://some.other.domain" + +config :pleroma, Pleroma.Upload, + base_url: "https://some.other.domain" +``` + +See `installation/pleroma-mediaproxy.nginx` for examples on how to configure your media proxy. + ## systemd A systemd unit example is provided at `installation/pleroma.service`. -- cgit v1.2.3 From 85902ad1ae5cfcc5d4c92cdb364a83d1edbbad3d Mon Sep 17 00:00:00 2001 From: tusooa Date: Fri, 26 May 2023 17:27:35 -0400 Subject: Recommend users to serve media on another domain in guide --- docs/installation/otp_en.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/installation/otp_en.md b/docs/installation/otp_en.md index f2812346b..ed52e57eb 100644 --- a/docs/installation/otp_en.md +++ b/docs/installation/otp_en.md @@ -198,6 +198,10 @@ $EDITOR path-to-nginx-config # Verify that the config is valid nginx -t ``` +#### (Strongly recommended) serve media on another domain + +Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors. + #### Start nginx === "Alpine" -- cgit v1.2.3 From e92eb5f4823fbb6c01218ec72ad8d41fb12e20a1 Mon Sep 17 00:00:00 2001 From: tusooa Date: Sat, 27 May 2023 00:57:22 +0000 Subject: Add instructions to other distro's guides --- docs/installation/alpine_linux_en.md | 3 +++ docs/installation/arch_linux_en.md | 5 +++++ docs/installation/debian_based_en.md | 5 +++++ docs/installation/freebsd_en.md | 4 ++++ docs/installation/gentoo_en.md | 4 ++++ docs/installation/netbsd_en.md | 4 ++++ docs/installation/openbsd_en.md | 4 ++++ 7 files changed, 29 insertions(+) (limited to 'docs') diff --git a/docs/installation/alpine_linux_en.md b/docs/installation/alpine_linux_en.md index c37ff0c63..7154bca48 100644 --- a/docs/installation/alpine_linux_en.md +++ b/docs/installation/alpine_linux_en.md @@ -183,6 +183,9 @@ server { ... } ``` +* (Strongly recommended) serve media on another domain + +Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors. * Enable and start nginx: diff --git a/docs/installation/arch_linux_en.md b/docs/installation/arch_linux_en.md index 285743d56..f7d722ef9 100644 --- a/docs/installation/arch_linux_en.md +++ b/docs/installation/arch_linux_en.md @@ -173,6 +173,11 @@ sudo ln -s /etc/nginx/sites-available/pleroma.nginx /etc/nginx/sites-enabled/ple ``` * Before starting nginx edit the configuration and change it to your needs (e.g. change servername, change cert paths) + +* (Strongly recommended) serve media on another domain + +Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors. + * Enable and start nginx: ```shell diff --git a/docs/installation/debian_based_en.md b/docs/installation/debian_based_en.md index 4e52b2155..fe85a05bf 100644 --- a/docs/installation/debian_based_en.md +++ b/docs/installation/debian_based_en.md @@ -136,6 +136,11 @@ sudo ln -s /etc/nginx/sites-available/pleroma.nginx /etc/nginx/sites-enabled/ple ``` * Before starting nginx edit the configuration and change it to your needs (e.g. change servername, change cert paths) + +* (Strongly recommended) serve media on another domain + +Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors. + * Enable and start nginx: ```shell diff --git a/docs/installation/freebsd_en.md b/docs/installation/freebsd_en.md index 9cbe0f203..50ed30d74 100644 --- a/docs/installation/freebsd_en.md +++ b/docs/installation/freebsd_en.md @@ -173,6 +173,10 @@ Edit the defaults of `/usr/local/etc/nginx/sites-available/pleroma.nginx`: * Change `ssl_certificate_key` to `/var/db/acme/certs/example.tld/example.tld.key`. * Change all references of `example.tld` to your instance's domain name. +#### (Strongly recommended) serve media on another domain + +Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors. + ## Creating a startup script for Pleroma Pleroma will need to compile when it initially starts, which typically takes a longer diff --git a/docs/installation/gentoo_en.md b/docs/installation/gentoo_en.md index 36882c8c8..693f83825 100644 --- a/docs/installation/gentoo_en.md +++ b/docs/installation/gentoo_en.md @@ -227,6 +227,10 @@ Replace all instances of `example.tld` with your instance's public URL. If for w Pay special attention to the line that begins with `ssl_ecdh_curve`. It is stongly advised to comment that line out so that OpenSSL will use its full capabilities, and it is also possible you are running OpenSSL 1.0.2 necessitating that you do this. +* (Strongly recommended) serve media on another domain + +Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors. + * Enable and start nginx: ```shell diff --git a/docs/installation/netbsd_en.md b/docs/installation/netbsd_en.md index 41b3b0072..2ade7df98 100644 --- a/docs/installation/netbsd_en.md +++ b/docs/installation/netbsd_en.md @@ -123,6 +123,10 @@ Edit the defaults: * Change `ssl_certificate_key` to `/etc/nginx/tls/key`. * Change `example.tld` to your instance's domain name. +### (Strongly recommended) serve media on another domain + +Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors. + ## Configuring acme.sh We'll be using acme.sh in Stateless Mode for TLS certificate renewal. diff --git a/docs/installation/openbsd_en.md b/docs/installation/openbsd_en.md index c80c8f678..9e7e040f5 100644 --- a/docs/installation/openbsd_en.md +++ b/docs/installation/openbsd_en.md @@ -195,6 +195,10 @@ rcctl enable relayd rcctl start relayd ``` +##### (Strongly recommended) serve media on another domain + +Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors. + #### pf Enabling and configuring pf is highly recommended. In /etc/pf.conf, insert the following configuration: -- cgit v1.2.3 From 9caa0b0be1feffb20b3eaccb48298de572d32393 Mon Sep 17 00:00:00 2001 From: Mark Felder Date: Mon, 29 May 2023 15:46:49 -0400 Subject: Add OnlyMedia Upload Filter to simplify restricting uploads to audio, image, and video types --- docs/configuration/cheatsheet.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index 70abe3e0c..026753f38 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -671,6 +671,12 @@ This filter reads the ImageDescription and iptc:Caption-Abstract fields with Exi No specific configuration. +#### Pleroma.Upload.Filter.OnlyMedia + +This filter rejects uploads that are not identified with Content-Type matching audio/*, image/*, or video/* + +No specific configuration. + #### Pleroma.Upload.Filter.Mogrify * `args`: List of actions for the `mogrify` command like `"strip"` or `["strip", "auto-orient", {"implode", "1"}]`. -- cgit v1.2.3 From 50a20f3bbd1203679c9295eb6002225dd630baf8 Mon Sep 17 00:00:00 2001 From: Mark Felder Date: Mon, 29 May 2023 15:53:16 -0400 Subject: Esacpe the asterisks in Markdown --- docs/configuration/cheatsheet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index 026753f38..1e49a79d0 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -673,7 +673,7 @@ No specific configuration. #### Pleroma.Upload.Filter.OnlyMedia -This filter rejects uploads that are not identified with Content-Type matching audio/*, image/*, or video/* +This filter rejects uploads that are not identified with Content-Type matching audio/\*, image/\*, or video/\* No specific configuration. -- cgit v1.2.3 From 8336519f300e2e12087126564a155c292915daed Mon Sep 17 00:00:00 2001 From: "Haelwenn (lanodan) Monnier" Date: Wed, 31 May 2023 08:26:21 +0200 Subject: installation/debian_based_en: Elixir 1.11 means Debian 12+ and Ubuntu 22.04+ --- docs/installation/debian_based_en.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/installation/debian_based_en.md b/docs/installation/debian_based_en.md index 4e52b2155..575b8a7ab 100644 --- a/docs/installation/debian_based_en.md +++ b/docs/installation/debian_based_en.md @@ -4,7 +4,7 @@ ## Installation -This guide will assume you are on Debian 11 (“bullseye”) or later. This guide should also work with Ubuntu 18.04 (“Bionic Beaver”) and later. It also assumes that you have administrative rights, either as root or a user with [sudo permissions](https://www.digitalocean.com/community/tutorials/how-to-add-delete-and-grant-sudo-privileges-to-users-on-a-debian-vps). If you want to run this guide with root, ignore the `sudo` at the beginning of the lines, unless it calls a user like `sudo -Hu pleroma`; in this case, use `su -s $SHELL -c 'command'` instead. +This guide will assume you are on Debian 12 (“bookworm”) or later. This guide should also work with Ubuntu 22.04 (“jammy”) and later. It also assumes that you have administrative rights, either as root or a user with [sudo permissions](https://www.digitalocean.com/community/tutorials/how-to-add-delete-and-grant-sudo-privileges-to-users-on-a-debian-vps). If you want to run this guide with root, ignore the `sudo` at the beginning of the lines, unless it calls a user like `sudo -Hu pleroma`; in this case, use `su -s $SHELL -c 'command'` instead. {! backend/installation/generic_dependencies.include !} -- cgit v1.2.3 From 737e45c1022172b316671110468a03a22a23e809 Mon Sep 17 00:00:00 2001 From: "Haelwenn (lanodan) Monnier" Date: Wed, 31 May 2023 08:28:28 +0200 Subject: installation/debian_based_jp: Elixir 1.11 means Debian 12+ and Ubuntu 22.04+ I checked for what each part of the debian&ubuntu sentences meant with the help of Jisho.org, should be safe but it did make me notice that this guide hasn't been updated in years --- docs/installation/debian_based_jp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/installation/debian_based_jp.md b/docs/installation/debian_based_jp.md index 3736e857f..695e7bb7d 100644 --- a/docs/installation/debian_based_jp.md +++ b/docs/installation/debian_based_jp.md @@ -5,7 +5,7 @@ ## インストール -このガイドはDebian Stretchを利用することを想定しています。Ubuntu 16.04や18.04でもおそらく動作します。また、ユーザはrootもしくはsudoにより管理者権限を持っていることを前提とします。もし、以下の操作をrootユーザで行う場合は、 `sudo` を無視してください。ただし、`sudo -Hu pleroma` のようにユーザを指定している場合には `su -s $SHELL -c 'command'` を代わりに使ってください。 +このガイドはDebian Bookwormを利用することを想定しています。Ubuntu 22.04でもおそらく動作します。また、ユーザはrootもしくはsudoにより管理者権限を持っていることを前提とします。もし、以下の操作をrootユーザで行う場合は、 `sudo` を無視してください。ただし、`sudo -Hu pleroma` のようにユーザを指定している場合には `su -s $SHELL -c 'command'` を代わりに使ってください。 ### 必要なソフトウェア -- cgit v1.2.3 From a2bbd7c9dadad42c995e7627a559673f04c2618b Mon Sep 17 00:00:00 2001 From: Sean King Date: Wed, 31 May 2023 12:22:13 -0600 Subject: Fix base media and proxy URL in instructions to serve media on another domain --- docs/configuration/hardening.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/configuration/hardening.md b/docs/configuration/hardening.md index 4f40873e6..493ba608c 100644 --- a/docs/configuration/hardening.md +++ b/docs/configuration/hardening.md @@ -68,10 +68,10 @@ It is STRONGLY RECOMMENDED to serve both the locally-uploaded media and the medi ```elixir config :pleroma, :media_proxy, - base_url: "https://some.other.domain" + base_url: "https://some.other.domain/proxy" config :pleroma, Pleroma.Upload, - base_url: "https://some.other.domain" + base_url: "https://some.other.domain/media" ``` See `installation/pleroma-mediaproxy.nginx` for examples on how to configure your media proxy. -- cgit v1.2.3 From c9cb90ff4fac5bf645720c7e7ef0bf4b6acf8afa Mon Sep 17 00:00:00 2001 From: Sean King Date: Wed, 31 May 2023 17:49:06 -0600 Subject: Media proxy base URL doesn't need /proxy --- docs/configuration/hardening.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/configuration/hardening.md b/docs/configuration/hardening.md index 493ba608c..cc46d1ff9 100644 --- a/docs/configuration/hardening.md +++ b/docs/configuration/hardening.md @@ -68,7 +68,7 @@ It is STRONGLY RECOMMENDED to serve both the locally-uploaded media and the medi ```elixir config :pleroma, :media_proxy, - base_url: "https://some.other.domain/proxy" + base_url: "https://some.other.domain" config :pleroma, Pleroma.Upload, base_url: "https://some.other.domain/media" -- cgit v1.2.3 From d5a7079f42228980471b6210aaaea69fcaa4c9ed Mon Sep 17 00:00:00 2001 From: "Haelwenn (lanodan) Monnier" Date: Tue, 13 Jun 2023 15:39:20 +0200 Subject: media_graphics_packages.md: Fix markdown syntax --- .../installation/optional/media_graphics_packages.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/installation/optional/media_graphics_packages.md b/docs/installation/optional/media_graphics_packages.md index de402d1c4..ad01d47d1 100644 --- a/docs/installation/optional/media_graphics_packages.md +++ b/docs/installation/optional/media_graphics_packages.md @@ -1,9 +1,10 @@ # Optional software packages needed for specific functionality For specific Pleroma functionality (which is disabled by default) some or all of the below packages are required: - * `ImageMagic` - * `ffmpeg` - * `exiftool` + +* `ImageMagic` +* `ffmpeg` +* `exiftool` Please refer to documentation in `docs/installation` on how to install them on specific OS. @@ -14,20 +15,23 @@ Note: the packages are not required with the current default settings of Pleroma `ImageMagick` is a set of tools to create, edit, compose, or convert bitmap images. It is required for the following Pleroma features: - * `Pleroma.Upload.Filters.Mogrify`, `Pleroma.Upload.Filters.Mogrifun` upload filters (related config: `Plaroma.Upload/filters` in `config/config.exs`) - * Media preview proxy for still images (related config: `media_preview_proxy/enabled` in `config/config.exs`) + +* `Pleroma.Upload.Filters.Mogrify`, `Pleroma.Upload.Filters.Mogrifun` upload filters (related config: `Plaroma.Upload/filters` in `config/config.exs`) +* Media preview proxy for still images (related config: `media_preview_proxy/enabled` in `config/config.exs`) ## `ffmpeg` `ffmpeg` is software to record, convert and stream audio and video. It is required for the following Pleroma features: - * Media preview proxy for videos (related config: `media_preview_proxy/enabled` in `config/config.exs`) + +* Media preview proxy for videos (related config: `media_preview_proxy/enabled` in `config/config.exs`) ## `exiftool` `exiftool` is media files metadata reader/writer. It is required for the following Pleroma features: - * `Pleroma.Upload.Filters.Exiftool.StripLocation` upload filter (related config: `Plaroma.Upload/filters` in `config/config.exs`) - * `Pleroma.Upload.Filters.Exiftool.ReadDescription` upload filter (related config: `Plaroma.Upload/filters` in `config/config.exs`) + +* `Pleroma.Upload.Filters.Exiftool.StripLocation` upload filter (related config: `Plaroma.Upload/filters` in `config/config.exs`) +* `Pleroma.Upload.Filters.Exiftool.ReadDescription` upload filter (related config: `Plaroma.Upload/filters` in `config/config.exs`) -- cgit v1.2.3 From 4392fff212b42204990569f396a69e74b053e5ca Mon Sep 17 00:00:00 2001 From: "Haelwenn (lanodan) Monnier" Date: Tue, 13 Jun 2023 15:40:12 +0200 Subject: otp_vs_from_source*: Acknowledge distro packages --- docs/installation/otp_vs_from_source.include | 9 +++++++-- docs/installation/otp_vs_from_source_source.include | 2 +- 2 files changed, 8 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/installation/otp_vs_from_source.include b/docs/installation/otp_vs_from_source.include index 63e837a53..6c7820275 100644 --- a/docs/installation/otp_vs_from_source.include +++ b/docs/installation/otp_vs_from_source.include @@ -1,3 +1,8 @@ -## OTP releases vs from-source installations +## Packaged (OTP) installation vs Manual (from-source) installations -There are two ways to install Pleroma. You can use OTP releases or do a from-source installation. 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. With from source installations you install Pleroma from source, meaning you have to install certain dependencies like Erlang+Elixir and compile Pleroma yourself. +There is multiple ways to install Pleroma. +
+
Distro-provided packages
This is the recommended method, where you can get the strongest compatibility guarantees and the best dependency-management
+
Pleroma-provided OTP binaries
Intended as fallback for Alpine/Debian-compatible systems lacking a proper Pleroma package, they are heavier than proper distro packages as they also contain Erlang/Elixir and can break after system updates
+
Manual from-source installation
Needs build-dependencies to be installed and manual updates+rebuilds. Allows for easier source-customisations.
+
diff --git a/docs/installation/otp_vs_from_source_source.include b/docs/installation/otp_vs_from_source_source.include index 63482b69d..9f7134229 100644 --- a/docs/installation/otp_vs_from_source_source.include +++ b/docs/installation/otp_vs_from_source_source.include @@ -1,3 +1,3 @@ {! backend/installation/otp_vs_from_source.include !} -This guide covers a from-source installation. To install using OTP releases, please check out [the OTP guide](./otp_en.md). +This guide covers a manual from-source installation. To install using OTP releases, please check for the presence of a distro package, failing that you can use [Pleroma-provided OTP binaries](./otp_en.md). -- cgit v1.2.3 From fb19f0d844eae80ff06015419119f7a709e5095f Mon Sep 17 00:00:00 2001 From: "Haelwenn (lanodan) Monnier" Date: Tue, 13 Jun 2023 15:40:48 +0200 Subject: gentoo_otp_en: Add packaged installation documentation --- docs/installation/gentoo_otp_en.md | 207 +++++++++++++++++++++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 docs/installation/gentoo_otp_en.md (limited to 'docs') diff --git a/docs/installation/gentoo_otp_en.md b/docs/installation/gentoo_otp_en.md new file mode 100644 index 000000000..5dcfe0b7b --- /dev/null +++ b/docs/installation/gentoo_otp_en.md @@ -0,0 +1,207 @@ +# Packaged install on Gentoo Linux + +{! backend/installation/otp_vs_from_source.include !} + +A [manual installation guide for gentoo](./gentoo_en.md) is also available. + +## Installation + +This guide will assume that you have administrative rights, either as root or a user with [sudo permissions](https://wiki.gentoo.org/wiki/Sudo). Lines that begin with `#` indicate that they should be run as the superuser. Lines using `$` should be run as the indicated user, e.g. `pleroma$` should be run as the `pleroma` user. + +{! backend/installation/generic_dependencies.include !} + +### Installing a cron daemon + +Gentoo quite pointedly does not come with a cron daemon installed, and as such it is recommended you install one to automate certbot renewals and to allow other system administration tasks to be run automatically. Gentoo has [a whole wide world of cron options](https://wiki.gentoo.org/wiki/Cron) but if you just want A Cron That Works, `emerge --ask virtual/cron` will install the default cron implementation (probably cronie) which will work just fine. For the purpouses of this guide, we will be doing just that. + +### Required ebuilds + +* `www-apps/pleroma` + +#### Optional ebuilds used in this guide + +* `www-servers/nginx` (preferred, example configs for other reverse proxies can be found in the repo) +* `app-crypt/certbot` (or any other ACME client for Let’s Encrypt certificates) +* `app-crypt/certbot-nginx` (nginx certbot plugin that allows use of the all-powerful `--nginx` flag on certbot) +* `media-gfx/imagemagick` +* `media-video/ffmpeg` +* `media-libs/exiftool` + +### Prepare the system + +* If you haven't yet done so, add the [Gentoo User Repository (GURU)](https://wiki.gentoo.org/wiki/Project:GURU), where the `www-apps/pleroma` ebuild currently lives at: +```shell + # eselect repository enable guru +``` + +* Ensure that you have the latest copy of the Gentoo and GURU ebuilds if you have not synced them yet: + +```shell + # emaint sync -a +``` + + +* Emerge all required the required and suggested software in one go: + +```shell + # emerge --ask www-apps/pleroma www-servers/nginx app-crypt/certbot app-crypt/certbot-nginx +``` + +If you would not like to install the optional packages, remove them from this line. + +If you're running this from a low-powered virtual machine, it should work though it will take some time. There were no issues on a VPS with a single core and 1GB of RAM; if you are using an even more limited device and run into issues, you can try creating a swapfile or use a more powerful machine running Gentoo to [cross build](https://wiki.gentoo.org/wiki/Cross_build_environment). If you have a wait ahead of you, now would be a good time to take a break, strech a bit, refresh your beverage of choice and/or get a snack, and reply to Arch users' posts with "I use Gentoo btw" as we do. + +### Setup PostgreSQL + +[Gentoo Wiki article](https://wiki.gentoo.org/wiki/PostgreSQL) as well as [PostgreSQL QuickStart](https://wiki.gentoo.org/wiki/PostgreSQL/QuickStart) might be worth a quick glance, as the way Gentoo handles postgres is slightly unusual, with built in capability to have two different databases running for testing and live or whatever other purpouse. While it is still straightforward to install, it does mean that the version numbers used in this guide might change for future updates, so keep an eye out for the output you get from `emerge` to ensure you are using the correct ones. + +* Initialize the database cluster + +The output from emerging postgresql should give you a command for initializing the postgres database. The default slot should be indicated in this command, ensure that it matches the command below. + +```shell + # emerge --config dev-db/postgresql:11 +``` + +### Install media / graphics packages (optional) + +See [Optional software packages needed for specific functionality](docs/installation/optional/media_graphics_packages.md) for details. + +```shell +# emerge --ask media-video/ffmpeg media-gfx/imagemagick media-libs/exiftool +``` + +### Setup PleromaBE + +* Generate the configuration: + +```shell + # pleroma_ctl instance gen --output /etc/pleroma/config.exs --output-psql /tmp/setup_db.psql" +``` + +* Create the PostgreSQL database + +```shell + # sudo -u postgres -s $SHELL -lc "psql -f /tmp/setup_db.psql" +``` + +* Now run the database migration: + +```shell + # pleroma_ctl migrate +``` + +* Optional: If you have installed RUM indexes (`dev-db/rum`) you also need to run: +``` + # sudo -Hu pleroma "pleroma_ctl migrate --migrations-path priv/repo/optional_migrations/rum_indexing/" +``` + +* Now you can start Pleroma already and add it in the default runlevel + +```shell + # rc-service pleroma start + # rc-update add pleroma default +``` + +It probably won't work over the public internet quite yet, however, as we still need to set up a web server to proxy to the pleroma application, as well as configure SSL. + +### Finalize installation + +Assuming you want to open your newly installed federated social network to, well, the federation, you should run nginx or some other webserver/proxy in front of Pleroma. It is also a good idea to set up Pleroma to run as a system service. + +#### Nginx + +* Install nginx, if not already done: + +```shell + # emerge --ask www-servers/nginx +``` + +* Create directories for available and enabled sites: + +```shell + # mkdir -p /etc/nginx/sites-{available,enabled} +``` + +* Append the following line at the end of the `http` block in `/etc/nginx/nginx.conf`: + +```Nginx +include sites-enabled/*; +``` + +* Setup your SSL cert, using your method of choice or certbot. If using certbot, install it if you haven't already: + +```shell + # emerge --ask app-crypt/certbot app-crypt/certbot-nginx +``` + +and then set it up: + +```shell + # mkdir -p /var/lib/letsencrypt/ + # certbot certonly --email -d --standalone +``` + +If that doesn't work the first time, add `--dry-run` to further attempts to avoid being ratelimited as you identify the issue, and do not remove it until the dry run succeeds. If that doesn’t work, make sure, that nginx is not already running. If it still doesn’t work, try setting up nginx first (change ssl “on” to “off” and try again). Often the answer to issues with certbot is to use the `--nginx` flag once you have nginx up and running. + +If you are using any additional subdomains, such as for a media proxy, you can re-run the same command with the subdomain in question. When it comes time to renew later, you will not need to run multiple times for each domain, one renew will handle it. + +--- + +* Copy the example nginx configuration and activate it: + +```shell + # cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/sites-available/ + # ln -s /etc/nginx/sites-available/pleroma.nginx /etc/nginx/sites-enabled/pleroma.nginx +``` + +* Take some time to ensure that your nginx config is correct + +Replace all instances of `example.tld` with your instance's public URL. If for whatever reason you made changes to the port that your pleroma app runs on, be sure that is reflected in your configuration. + +Pay special attention to the line that begins with `ssl_ecdh_curve`. It is stongly advised to comment that line out so that OpenSSL will use its full capabilities, and it is also possible you are running OpenSSL 1.0.2 necessitating that you do this. + +* Enable and start nginx: + +```shell + # rc-update add nginx default + # /etc/init.d/nginx start +``` + +If you are using certbot, it is HIGHLY recommend you set up a cron job that renews your certificate, and that you install the suggested `certbot-nginx` plugin. If you don't do these things, you only have yourself to blame when your instance breaks suddenly because you forgot about it. + +First, ensure that the command you will be installing into your crontab works. + +```shell + # /usr/bin/certbot renew --nginx +``` + +Assuming not much time has passed since you got certbot working a few steps ago, you should get a message for all domains you installed certificates for saying `Cert not yet due for renewal`. + +Now, run crontab as a superuser with `crontab -e` or `sudo crontab -e` as appropriate, and add the following line to your cron: + +```cron +0 0 1 * * /usr/bin/certbot renew --nginx +``` + +This will run certbot on the first of the month at midnight. If you'd rather run more frequently, it's not a bad idea, feel free to go for it. + +#### Other webserver/proxies + +If you would like to use other webservers or proxies, there are example configurations for some popular alternatives in `/opt/pleroma/installation/`. You can, of course, check out [the Gentoo wiki](https://wiki.gentoo.org) for more information on installing and configuring said alternatives. + +#### Create your first user + +If your instance is up and running, you can create your first user with administrative rights with the following task: + +```shell +pleroma$ pleroma_ctl user new --admin +``` + +#### Further reading + +{! backend/installation/further_reading.include !} + +## 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. -- cgit v1.2.3 From eddfd41c1f2fb15f5a28b5474a64bed7b86d62d7 Mon Sep 17 00:00:00 2001 From: "Haelwenn (lanodan) Monnier" Date: Tue, 13 Jun 2023 15:41:09 +0200 Subject: gentoo_en: Reference packaged installation --- docs/installation/gentoo_en.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/installation/gentoo_en.md b/docs/installation/gentoo_en.md index 36882c8c8..02a3c709b 100644 --- a/docs/installation/gentoo_en.md +++ b/docs/installation/gentoo_en.md @@ -1,6 +1,8 @@ -# Installing on Gentoo GNU/Linux +# Manual install on Gentoo GNU/Linux -{! backend/installation/otp_vs_from_source_source.include !} +{! backend/installation/otp_vs_from_source.include !} + +This guide covers a manual from-source installation. To use the gentoo package, please check the [packaged installation guide for gentoo](./gentoo.en.md). ## Installation -- cgit v1.2.3 From 8fa435f370cd1a85a37eae011d9db604256fbef1 Mon Sep 17 00:00:00 2001 From: tusooa Date: Wed, 14 Jun 2023 21:48:10 +0000 Subject: Add "potentially outdated" notice in non-English versions --- docs/installation/debian_based_jp.md | 3 +++ docs/installation/openbsd_fi.md | 2 ++ 2 files changed, 5 insertions(+) (limited to 'docs') diff --git a/docs/installation/debian_based_jp.md b/docs/installation/debian_based_jp.md index 3736e857f..2489e3473 100644 --- a/docs/installation/debian_based_jp.md +++ b/docs/installation/debian_based_jp.md @@ -1,4 +1,7 @@ # Pleromaの入れ方 + +Note: This article is potentially outdated because at this time we may not have people who can speak this language well enough to update it. To see the up-to-date version, which may have significant differences or important caveats of the installation process, look up the English version. + ## 日本語訳について この記事は [Installing on Debian based distributions](Installing on Debian based distributions) の日本語訳です。何かがおかしいと思ったら、原文を見てください。 diff --git a/docs/installation/openbsd_fi.md b/docs/installation/openbsd_fi.md index 3c40b2d1a..73aca3a6f 100644 --- a/docs/installation/openbsd_fi.md +++ b/docs/installation/openbsd_fi.md @@ -1,5 +1,7 @@ # Pleroman asennus OpenBSD:llä +Note: This article is potentially outdated because at this time we may not have people who can speak this language well enough to update it. To see the up-to-date version, which may have significant differences or important caveats of the installation process, look up the English version. + Tarvitset: * Oman domainin * OpenBSD 6.3 -serverin -- cgit v1.2.3 From 3d79ceb23a3dc9630d38807cf6e8a62a56f29d3b Mon Sep 17 00:00:00 2001 From: "Haelwenn (lanodan) Monnier" Date: Tue, 4 Jul 2023 03:34:51 +0200 Subject: Deprecate audio scrobbling --- docs/development/API/pleroma_api.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/development/API/pleroma_api.md b/docs/development/API/pleroma_api.md index 47fcb7479..bd0e07f9e 100644 --- a/docs/development/API/pleroma_api.md +++ b/docs/development/API/pleroma_api.md @@ -577,6 +577,9 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa 404 if the pack does not exist ## `GET /api/v1/pleroma/accounts/:id/scrobbles` + +Audio scrobbling in Pleroma is **deprecated**. + ### Requests a list of current and recent Listen activities for an account * Method `GET` * Authentication: not required @@ -598,6 +601,9 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa ``` ## `POST /api/v1/pleroma/scrobble` + +Audio scrobbling in Pleroma is **deprecated**. + ### Creates a new Listen activity for an account * Method `POST` * Authentication: required -- cgit v1.2.3 From 0c3709173fe7905c3d7e9d542d3b1007d8f97042 Mon Sep 17 00:00:00 2001 From: "Haelwenn (lanodan) Monnier" Date: Tue, 4 Jul 2023 04:19:25 +0200 Subject: docs: Fix broken links --- docs/installation/gentoo_en.md | 2 +- docs/installation/gentoo_otp_en.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/installation/gentoo_en.md b/docs/installation/gentoo_en.md index 273e21d4b..87128d6f6 100644 --- a/docs/installation/gentoo_en.md +++ b/docs/installation/gentoo_en.md @@ -2,7 +2,7 @@ {! backend/installation/otp_vs_from_source.include !} -This guide covers a manual from-source installation. To use the gentoo package, please check the [packaged installation guide for gentoo](./gentoo.en.md). +This guide covers a manual from-source installation. To use the gentoo package, please check the [packaged installation guide for gentoo](./gentoo_otp_en.md). ## Installation diff --git a/docs/installation/gentoo_otp_en.md b/docs/installation/gentoo_otp_en.md index 5dcfe0b7b..76968eb38 100644 --- a/docs/installation/gentoo_otp_en.md +++ b/docs/installation/gentoo_otp_en.md @@ -65,7 +65,7 @@ The output from emerging postgresql should give you a command for initializing t ### Install media / graphics packages (optional) -See [Optional software packages needed for specific functionality](docs/installation/optional/media_graphics_packages.md) for details. +See [Optional software packages needed for specific functionality](optional/media_graphics_packages.md) for details. ```shell # emerge --ask media-video/ffmpeg media-gfx/imagemagick media-libs/exiftool -- cgit v1.2.3 From 18a8378beb01a7ee93afcddf16e2699c5fe6d35a Mon Sep 17 00:00:00 2001 From: tusooa Date: Tue, 28 Feb 2023 12:05:54 -0500 Subject: Update config cheatsheet --- docs/configuration/cheatsheet.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs') diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index 1e49a79d0..696d10e74 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -261,6 +261,11 @@ Notes: * `follower_nickname`: The name of the bot account to use for following newly discovered users. Using `followbot` or similar is strongly suggested. +#### :mrf_emoji +* `remove_url`: A list of patterns which result in emoji whose URL matches being removed from the message. This will apply to both statuses and user profiles. Each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html). +* `remove_shortcode`: A list of patterns which result in emoji whose shortcode matches being removed from the message. This will apply to both statuses and user profiles. Each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html). +* `federated_timeline_removal_url`: A list of patterns which result in message with emojis whose URLs match being removed from federated timelines (a.k.a unlisted). This will apply only to statuses. Each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html). +* `federated_timeline_removal_shortcode`: A list of patterns which result in message with emojis whose shortcodes match being removed from federated timelines (a.k.a unlisted). This will apply only to statuses. Each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html). ### :activitypub * `unfollow_blocked`: Whether blocks result in people getting unfollowed -- cgit v1.2.3 From ef8a6c539a98633d1a78fa42379952b93f847309 Mon Sep 17 00:00:00 2001 From: tusooa Date: Tue, 13 Jun 2023 14:53:20 -0400 Subject: Make EmojiPolicy aware of custom emoji reactions --- docs/configuration/cheatsheet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index 696d10e74..f43cde114 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -262,8 +262,8 @@ Notes: * `follower_nickname`: The name of the bot account to use for following newly discovered users. Using `followbot` or similar is strongly suggested. #### :mrf_emoji -* `remove_url`: A list of patterns which result in emoji whose URL matches being removed from the message. This will apply to both statuses and user profiles. Each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html). -* `remove_shortcode`: A list of patterns which result in emoji whose shortcode matches being removed from the message. This will apply to both statuses and user profiles. Each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html). +* `remove_url`: A list of patterns which result in emoji whose URL matches being removed from the message. This will apply to statuses, emoji reactions, and user profiles. Each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html). +* `remove_shortcode`: A list of patterns which result in emoji whose shortcode matches being removed from the message. This will apply to statuses, emoji reactions, and user profiles. Each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html). * `federated_timeline_removal_url`: A list of patterns which result in message with emojis whose URLs match being removed from federated timelines (a.k.a unlisted). This will apply only to statuses. Each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html). * `federated_timeline_removal_shortcode`: A list of patterns which result in message with emojis whose shortcodes match being removed from federated timelines (a.k.a unlisted). This will apply only to statuses. Each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html). -- cgit v1.2.3 From 0e321698d21766772aa2b54b518dcd76a6abce8c Mon Sep 17 00:00:00 2001 From: "Haelwenn (lanodan) Monnier" Date: Fri, 4 Aug 2023 17:09:50 +0200 Subject: gentoo_otp_en.md: Indicate which install method it covers --- docs/installation/gentoo_otp_en.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/installation/gentoo_otp_en.md b/docs/installation/gentoo_otp_en.md index 76968eb38..4fafc0c17 100644 --- a/docs/installation/gentoo_otp_en.md +++ b/docs/installation/gentoo_otp_en.md @@ -2,7 +2,7 @@ {! backend/installation/otp_vs_from_source.include !} -A [manual installation guide for gentoo](./gentoo_en.md) is also available. +This guide covers installation via Gentoo provided packaging. A [manual installation guide for gentoo](./gentoo_en.md) is also available. ## Installation -- cgit v1.2.3 From 57ef1d121101d785c043ef6aaf2d33bb9be3ec3b Mon Sep 17 00:00:00 2001 From: Alex Gleason Date: Mon, 24 Jan 2022 16:44:35 -0600 Subject: Add InlineQuotePolicy to force quote URLs inline --- docs/configuration/cheatsheet.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index f43cde114..32cc5811a 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -160,6 +160,7 @@ To add configuration to your config file, you can copy it from the base config. * `Pleroma.Web.ActivityPub.MRF.AntiFollowbotPolicy`: Drops follow requests from followbots. Users can still allow bots to follow them by first following the bot. * `Pleroma.Web.ActivityPub.MRF.KeywordPolicy`: Rejects or removes from the federated timeline or replaces keywords. (See [`:mrf_keyword`](#mrf_keyword)). * `Pleroma.Web.ActivityPub.MRF.ForceMentionsInContent`: Forces every mentioned user to be reflected in the post content. + * `Pleroma.Web.ActivityPub.MRF.InlineQuotePolicy`: Forces quote post URLs to be reflected in the message content inline. * `transparency`: Make the content of your Message Rewrite Facility settings public (via nodeinfo). * `transparency_exclusions`: Exclude specific instance names from MRF transparency. The use of the exclusions feature will be disclosed in nodeinfo as a boolean value. @@ -267,6 +268,9 @@ Notes: * `federated_timeline_removal_url`: A list of patterns which result in message with emojis whose URLs match being removed from federated timelines (a.k.a unlisted). This will apply only to statuses. Each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html). * `federated_timeline_removal_shortcode`: A list of patterns which result in message with emojis whose shortcodes match being removed from federated timelines (a.k.a unlisted). This will apply only to statuses. Each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html). +#### :mrf_inline_quote +* `prefix`: Prefix before the link (default: `RT`) + ### :activitypub * `unfollow_blocked`: Whether blocks result in people getting unfollowed * `outgoing_blocks`: Whether to federate blocks to other instances -- cgit v1.2.3 From 163e5637335f9454688d3cc83530f82fc640a5b9 Mon Sep 17 00:00:00 2001 From: tusooa Date: Wed, 12 Jul 2023 09:30:43 -0400 Subject: Allow more flexibility in InlineQuotePolicy --- docs/configuration/cheatsheet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index 32cc5811a..a17f8735a 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -269,7 +269,7 @@ Notes: * `federated_timeline_removal_shortcode`: A list of patterns which result in message with emojis whose shortcodes match being removed from federated timelines (a.k.a unlisted). This will apply only to statuses. Each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html). #### :mrf_inline_quote -* `prefix`: Prefix before the link (default: `RT`) +* `template`: The template to append to the post. `{url}` will be replaced with the actual link to the quoted post. Default: `RT: {url}` ### :activitypub * `unfollow_blocked`: Whether blocks result in people getting unfollowed -- cgit v1.2.3 From e349e92a441840bbbdbf13cacd307e65f85a38ff Mon Sep 17 00:00:00 2001 From: tusooa Date: Wed, 12 Jul 2023 14:27:29 -0400 Subject: Add mrf to force link tag of quoting posts --- docs/configuration/cheatsheet.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index a17f8735a..a4cae4dbb 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -161,6 +161,7 @@ To add configuration to your config file, you can copy it from the base config. * `Pleroma.Web.ActivityPub.MRF.KeywordPolicy`: Rejects or removes from the federated timeline or replaces keywords. (See [`:mrf_keyword`](#mrf_keyword)). * `Pleroma.Web.ActivityPub.MRF.ForceMentionsInContent`: Forces every mentioned user to be reflected in the post content. * `Pleroma.Web.ActivityPub.MRF.InlineQuotePolicy`: Forces quote post URLs to be reflected in the message content inline. + * `Pleroma.Web.ActivityPub.MRF.QuoteToLinkTagPolicy`: Force a Link tag for posts quoting another post. (may break outgoing federation of quote posts with older Pleroma versions) * `transparency`: Make the content of your Message Rewrite Facility settings public (via nodeinfo). * `transparency_exclusions`: Exclude specific instance names from MRF transparency. The use of the exclusions feature will be disclosed in nodeinfo as a boolean value. -- cgit v1.2.3 From 2d430679468a4c6a9b5c365a53f007cfa28679d9 Mon Sep 17 00:00:00 2001 From: tusooa Date: Sat, 1 Apr 2023 02:24:30 -0400 Subject: Document the streaming endpoint --- .../API/differences_in_mastoapi_responses.md | 116 +++++++++++++++++++++ 1 file changed, 116 insertions(+) (limited to 'docs') diff --git a/docs/development/API/differences_in_mastoapi_responses.md b/docs/development/API/differences_in_mastoapi_responses.md index 4007c63c8..ef6b3b3be 100644 --- a/docs/development/API/differences_in_mastoapi_responses.md +++ b/docs/development/API/differences_in_mastoapi_responses.md @@ -357,6 +357,122 @@ The message payload consist of: - `follower_count`: follower count - `following_count`: following count +### Authenticating via `sec-websocket-protocol` header + +Pleroma allows to authenticate via the `sec-websocket-protocol` header, for example, if your access token is `your-access-token`, you can authenticate using the following: + +``` +sec-websocket-protocol: your-access-token +``` + +### Authenticating after connection via `pleroma:authenticate` event + +Pleroma allows to authenticate after connection is established, via the `pleroma:authenticate` event. For example, if your access token is `your-access-token`, you can send the following after the connection is established: + +``` +{"type": "pleroma:authenticate", "token": "your-access-token"} +``` + +### Response to client-sent events + +Pleroma will respond to client-sent events that it recognizes. Supported event types are: + +- `subscribe` +- `unsubscribe` +- `pleroma:authenticate` + +The reply will be in the following format: + +``` +{ + "event": "pleroma:respond", + "payload": "{\"type\": \"\", \"result\": \"\", \"error\": \"\"}" +} +``` + +Result of the action can be either `success`, `ignored` or `error`. If it is `error`, the `error` property will contain the error code. Otherwise, the `error` property will not be present. Below are some examples: + +``` +{ + "event": "pleroma:respond", + "payload": "{\"type\": \"pleroma:authenticate\", \"result\": \"success\"}" +} + +{ + "event": "pleroma:respond", + "payload": "{\"type\": \"subscribe\", \"result\": \"ignored\"}" +} + +{ + "event": "pleroma:respond", + "payload": "{\"type\": \"unsubscribe\", \"result\": \"error\", \"error\": \"bad_topic\"}" +} +``` + +If the sent event is not of a type that Pleroma supports, it will not reply. + +### The `stream` attribute of a server-sent event + +Technically, this is in Mastodon, but its documentation does nothing to specify its format. + +This attribute appears on every event type except `pleroma:respond` and `delete`. It helps clients determine where they should display the new statuses. + +The value of the attribute is an array containing one or two elements. The first element is the type of the stream. The second is the identifier related to that specific stream, if applicable. + +For the following stream types, there is a second element in the array: + +- `list`: The second element is the id of the list. +- `hashtag`: The second element is the name of the hashtag. +- `public:remote:media` and `public:remote`: The second element is the domain of the corresponding instance. + +For all other stream types, there is no second element. + +Some examples of valid `stream` values: + +- `list:1`: List of id 1. +- `hashtag:mew`: The hashtag #mew. +- `user:notifications`: Notifications for the current user. +- `user`: Home timeline. +- `public:remote:mew.moe`: Public posts from the instance mew.moe . + +### The unified streaming endpoint + +If you do not specify a stream to connect to when requesting `/api/v1/streaming`, you will enter a connection that subscribes to no streams. After the connection is established, you can authenticate and then subscribe to different streams. + +### List of supported streams + +Below is a list of supported streams by Pleroma. To make a single-stream WebSocket connection, append the string specified in "Query style" to the streaming endpoint url. +To subscribe to a stream after the connection is established, merge the JSON object specified in "Subscribe style" with `{"type": "subscribe"}`. To unsubscribe, merge it with `{"type": "unsubscribe"}`. + +For example, to receive updates on the list 1, you can connect to `/api/v1/streaming/?stream=list&list=1`, or send + +``` +{"type": "subscribe", "stream": "list", "list": 1} +``` + +upon establishing the websocket connection. + +To unsubscribe to list 1, send + +``` +{"type": "unsubscribe", "stream": "list", "list": 1} +``` + +Note that if you specify a stream that requires a logged-in user in the query string (for example, `user` or `list`), you have to specify the access token when you are trying to establish the connection, i.e. in the query string or via the `sec-websocket-protocol` header. + +- `list` + - Query style: `?stream=list&list=` + - Subscribe style: `{"stream": "list", "list": }` +- `public`, `public:local`, `public:media`, `public:local:media`, `user`, `user:pleroma_chat`, `user:notifications`, `direct` + - Query style: `?stream=` + - Subscribe style: `{"stream": ""}` +- `hashtag` + - Query style: `?stream=hashtag&tag=` + - Subscribe style: `{"stream": "hashtag", "tag": ""}` +- `public:remote`, `public:remote:media` + - Query style: `?stream=&instance=` + - Subscribe style: `{"stream": "", "instance": ""}` + ## User muting and thread muting Both user muting and thread muting can be done for only a certain time by adding an `expires_in` parameter to the API calls and giving the expiration time in seconds. -- cgit v1.2.3 From 7f12ad6dccfe4c81fa7e0d4e66c43bedadbf4c6a Mon Sep 17 00:00:00 2001 From: tusooa Date: Sat, 1 Apr 2023 02:37:19 -0400 Subject: Fix docs wording --- .../API/differences_in_mastoapi_responses.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/development/API/differences_in_mastoapi_responses.md b/docs/development/API/differences_in_mastoapi_responses.md index ef6b3b3be..48a9c104c 100644 --- a/docs/development/API/differences_in_mastoapi_responses.md +++ b/docs/development/API/differences_in_mastoapi_responses.md @@ -421,7 +421,7 @@ The value of the attribute is an array containing one or two elements. The first For the following stream types, there is a second element in the array: -- `list`: The second element is the id of the list. +- `list`: The second element is the id of the list, as a string. - `hashtag`: The second element is the name of the hashtag. - `public:remote:media` and `public:remote`: The second element is the domain of the corresponding instance. @@ -429,11 +429,11 @@ For all other stream types, there is no second element. Some examples of valid `stream` values: -- `list:1`: List of id 1. -- `hashtag:mew`: The hashtag #mew. -- `user:notifications`: Notifications for the current user. -- `user`: Home timeline. -- `public:remote:mew.moe`: Public posts from the instance mew.moe . +- `["list", "1"]`: List of id 1. +- `["hashtag", "mew"]`: The hashtag #mew. +- `["user:notifications"]`: Notifications for the current user. +- `["user"]`: Home timeline. +- `["public:remote", "mew.moe"]`: Public posts from the instance mew.moe . ### The unified streaming endpoint @@ -447,7 +447,7 @@ To subscribe to a stream after the connection is established, merge the JSON obj For example, to receive updates on the list 1, you can connect to `/api/v1/streaming/?stream=list&list=1`, or send ``` -{"type": "subscribe", "stream": "list", "list": 1} +{"type": "subscribe", "stream": "list", "list": "1"} ``` upon establishing the websocket connection. @@ -455,14 +455,14 @@ upon establishing the websocket connection. To unsubscribe to list 1, send ``` -{"type": "unsubscribe", "stream": "list", "list": 1} +{"type": "unsubscribe", "stream": "list", "list": "1"} ``` Note that if you specify a stream that requires a logged-in user in the query string (for example, `user` or `list`), you have to specify the access token when you are trying to establish the connection, i.e. in the query string or via the `sec-websocket-protocol` header. - `list` - Query style: `?stream=list&list=` - - Subscribe style: `{"stream": "list", "list": }` + - Subscribe style: `{"stream": "list", "list": ""}` - `public`, `public:local`, `public:media`, `public:local:media`, `user`, `user:pleroma_chat`, `user:notifications`, `direct` - Query style: `?stream=` - Subscribe style: `{"stream": ""}` -- cgit v1.2.3 From 637926dcbb6b607fb91eed9be2f8a7169c7729c3 Mon Sep 17 00:00:00 2001 From: Henry Jameson Date: Fri, 10 Nov 2023 13:58:25 +0200 Subject: Initial draft on frontends management --- docs/administration/frontends-management.md | 71 +++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 docs/administration/frontends-management.md (limited to 'docs') diff --git a/docs/administration/frontends-management.md b/docs/administration/frontends-management.md new file mode 100644 index 000000000..a311a326e --- /dev/null +++ b/docs/administration/frontends-management.md @@ -0,0 +1,71 @@ +# Managing installed frontends + +Pleroma lets you install multiple frontends including multiple versions of same frontend. Right now it's only possible to switch which frontend is the default, but in the future it would be possible for user to select which frontend they prefer to use. + +As of 2.6.0 there are two ways of managing frontends - through PleromaFE's Admin Dashboard (preferred, easier method) or through AdminFE (clunky but also works on versions older than 2.6.0). + +!!! note + Managing frontends through UI requires [in-database configuration](../configuration/howto_database_config.md) to be enabled (default on newer instances but might be off on older ones). + +## How it works + +When installing frontends, it creates a folder in [static directory](../configuration/static_dir.md) that follows this pattern: `/frontends/${front-end name}/${front-end version}/`, puts contents of the built frontend in there. Then when accessing the server backend checks what front-end name and version are set to be default and serves index.html and assets from appropriate path. + +!!! warning + + If you've been putting your frontend build directly into static dir as an antiquated way of serving custom frontend, this system will not work and will still serve the custom index.html you put in there. You can still serve custom frontend builds if you put your build into `/frontends/$name/$version` instead and set the "default frontend" fields appropriately. + +Currently, there is no backup system, i.e. when installing `master` version it _will_ overwrite installed `master` version, for now if you want to keep previous version you should back it up manually, i.e. running `cp -r ./frontends/pleroma-fe/master ./frontends/pleroma-fe/master_old` in your static dir. + +## Managing front-ends through Admin Dashboard + +Open up Admin Dashboard (gauge icon in top bar, same as where link to AdminFE was), switch to "Front-ends" tab. +IMAGE HERE +This page is designed to be self-explanatory and easy to use, while avoiding issues and pitfalls of AdminFE, but it's also early in development, everything is subject to change. + +!!! bug + As of PleromaFE 2.6.0 there is no feedback on whether frontend is installing, installed or failed to install, this will be fixed in PleromaFE 2.6.1. + +!!! warning + This goes without saying, but if you set default frontend to anything except >2.6.0 version of PleromaFE you'll lose the access to Admin Dashboard and will have to use AdminFE to get it back. See below on how to use AdminFE. + +### Limitations + +Currently the list of available for install frontends is essentially hard-coded in backend's configuration, each providing only one version, with exception for PleromaFE which overrides 'pleroma-fe' to also include `develop` version. There is no way to manually install build with a URL (coming soon) nor add more available frontends to the repository (it's broken). + +There is also no way to tell if there is an update available or not, for now you should watch for [announcements](https://pleroma.social/announcements/) of new PleromaFE stable releases to see if there is new stable version. For `develop` version it's up to you whether you want to follow the development process or just reinstall it periodically hoping for new stuff. + +## Using AdminFE to manage frontends + +Access AdminFE either directly by going to `/pleroma/admin` of your instance or by opening Admin Dashboard and clicking the link below +IMAGE HERE + +Go to Settings -> Frontend. + +### Installing front-ends + +At the very top of the page there's a list of available frontends and button to install custom front-end + +!!! tip + Remember to click "Submit" in bottom right corner to save your changes! + +!!! bug + **Available Frontends** section lets you _install_ frontends but **NOT** update/reinstall them. It's only useful for installing a frontend once. + +Due to aforementioned bug, preferred way of installing frontends in AdminFE is by clicking the "Install another frontend" +IMAGE HERE +and filling in the fields. Unfortunately AdminFE does not provide the raw data necessary for you to fill those fields, so your best bet is to see what backend returns in browser's devtools or refer to the [source code](https://git.pleroma.social/pleroma/pleroma/-/blob/develop/config/config.exs?ref_type=heads#L742-791). For the most part, only **Name**, **Ref** (i.e. version) and **Build URL** fields are required, although some frontends might also require **Build Directory** to work. + +For pleroma-fe you can use either `master` or `develop` refs, or potentially any ref in GitLab that has artifacts for `build` job, but that's outside scope of this document. + +### Selecting default frontend + +Scroll page waaaaay down, search for "Frontends" section, subtitled "Installed frontends management", change the name and reference of the "Primary" frontend. +IMAGE HERE + + +!!! danger + If you change "Admin" frontend name/reference you risk losing access to AdminFE as well. + +!!! warning + Don't put anything into the "Available" section as it will break the list of available frontends completely, including the "add another frontend" button. If you accidentally put something in there, click the trashbin icon next to "Available" to reset it and restore the frontends list. -- cgit v1.2.3 From 3831d310091fe975893972185baa592789194952 Mon Sep 17 00:00:00 2001 From: "Haelwenn (lanodan) Monnier" Date: Fri, 1 Sep 2023 19:32:59 +0200 Subject: docs: Put a max version on erlang and elixir Closes: https://git.pleroma.social/pleroma/pleroma/-/issues/3194 --- docs/installation/generic_dependencies.include | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/installation/generic_dependencies.include b/docs/installation/generic_dependencies.include index dcaacfdfd..dbe6fe49d 100644 --- a/docs/installation/generic_dependencies.include +++ b/docs/installation/generic_dependencies.include @@ -1,8 +1,8 @@ ## Required dependencies -* PostgreSQL 9.6+ -* Elixir 1.10+ -* Erlang OTP 22.2+ +* PostgreSQL >=9.6 +* Elixir >=1.11.0 <1.15 +* Erlang OTP >=22.2.0 <26 * git * file / libmagic * gcc (clang might also work) -- cgit v1.2.3 From 19519d6c969196f2b1d9283168060a751068472d Mon Sep 17 00:00:00 2001 From: "Haelwenn (lanodan) Monnier" Date: Fri, 1 Sep 2023 19:33:27 +0200 Subject: docs: clang is also supported --- docs/installation/generic_dependencies.include | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/installation/generic_dependencies.include b/docs/installation/generic_dependencies.include index dbe6fe49d..3365a36a8 100644 --- a/docs/installation/generic_dependencies.include +++ b/docs/installation/generic_dependencies.include @@ -5,7 +5,7 @@ * Erlang OTP >=22.2.0 <26 * git * file / libmagic -* gcc (clang might also work) +* gcc or clang * GNU make * CMake -- cgit v1.2.3 From be39146ecc6d55191f8ed3ec9cd3e113d8ee5e21 Mon Sep 17 00:00:00 2001 From: Mark Felder Date: Fri, 17 Nov 2023 11:44:33 -0500 Subject: Update docs to include dependencies on rust and vips where appropriate --- docs/installation/alpine_linux_en.md | 2 +- docs/installation/arch_linux_en.md | 1 + docs/installation/debian_based_en.md | 2 +- docs/installation/debian_based_jp.md | 1 + docs/installation/freebsd_en.md | 3 ++- 5 files changed, 6 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/installation/alpine_linux_en.md b/docs/installation/alpine_linux_en.md index 7154bca48..9794833a3 100644 --- a/docs/installation/alpine_linux_en.md +++ b/docs/installation/alpine_linux_en.md @@ -28,7 +28,7 @@ sudo apk upgrade * Install some tools, which are needed later: ```shell -sudo apk add git build-base cmake file-dev +sudo apk add git build-base cmake file-dev rust ``` ### Install Elixir and Erlang diff --git a/docs/installation/arch_linux_en.md b/docs/installation/arch_linux_en.md index f7d722ef9..dbfbf6bf8 100644 --- a/docs/installation/arch_linux_en.md +++ b/docs/installation/arch_linux_en.md @@ -14,6 +14,7 @@ This guide will assume that you have administrative rights, either as root or a * `base-devel` * `cmake` * `file` +* `rust` #### Optional packages used in this guide diff --git a/docs/installation/debian_based_en.md b/docs/installation/debian_based_en.md index b61e4addd..44c93e1ef 100644 --- a/docs/installation/debian_based_en.md +++ b/docs/installation/debian_based_en.md @@ -20,7 +20,7 @@ sudo apt full-upgrade * Install some of the above mentioned programs: ```shell -sudo apt install git build-essential postgresql postgresql-contrib cmake libmagic-dev +sudo apt install git build-essential postgresql postgresql-contrib cmake libmagic-dev rust ``` ### Install Elixir and Erlang diff --git a/docs/installation/debian_based_jp.md b/docs/installation/debian_based_jp.md index 1424ad7f4..43902c987 100644 --- a/docs/installation/debian_based_jp.md +++ b/docs/installation/debian_based_jp.md @@ -21,6 +21,7 @@ Note: This article is potentially outdated because at this time we may not have - `build-essential` - `cmake` - `libmagic-dev` +- `rust` #### このガイドで利用している追加パッケージ diff --git a/docs/installation/freebsd_en.md b/docs/installation/freebsd_en.md index 50ed30d74..b88853dd1 100644 --- a/docs/installation/freebsd_en.md +++ b/docs/installation/freebsd_en.md @@ -9,7 +9,7 @@ This document was written for FreeBSD 12.1, but should be work on future release This assumes the target system has `pkg(8)`. ``` -# pkg install elixir postgresql12-server postgresql12-client postgresql12-contrib git-lite sudo nginx gmake acme.sh cmake +# pkg install elixir postgresql12-server postgresql12-client postgresql12-contrib git-lite sudo nginx gmake acme.sh cmake rust vips ``` Copy the rc.d scripts to the right directory: @@ -41,6 +41,7 @@ Create a user for Pleroma: ``` # pw add user pleroma -m # echo 'export LC_ALL="en_US.UTF-8"' >> /home/pleroma/.profile +# echo 'export VIX_COMPILATION_MODE=PLATFORM_PROVIDED_LIBVIPS' >> /home/pleroma/.profile # su -l pleroma ``` -- cgit v1.2.3 From 2112e8b5e443a969725f85745b50886335806437 Mon Sep 17 00:00:00 2001 From: Henry Jameson Date: Sun, 19 Nov 2023 10:30:49 +0200 Subject: update, add images --- docs/administration/frontends-management.md | 18 +++++++++--------- docs/assets/admin_dash_location.png | Bin 0 -> 8698 bytes docs/assets/frontends_tab.png | Bin 0 -> 148269 bytes docs/assets/old_adminfe_link.png | Bin 0 -> 15143 bytes docs/assets/primary_frontend_section.png | Bin 0 -> 26498 bytes docs/assets/way_to_install_frontends.png | Bin 0 -> 130193 bytes 6 files changed, 9 insertions(+), 9 deletions(-) create mode 100644 docs/assets/admin_dash_location.png create mode 100644 docs/assets/frontends_tab.png create mode 100644 docs/assets/old_adminfe_link.png create mode 100644 docs/assets/primary_frontend_section.png create mode 100644 docs/assets/way_to_install_frontends.png (limited to 'docs') diff --git a/docs/administration/frontends-management.md b/docs/administration/frontends-management.md index a311a326e..f982c4bca 100644 --- a/docs/administration/frontends-management.md +++ b/docs/administration/frontends-management.md @@ -19,13 +19,12 @@ Currently, there is no backup system, i.e. when installing `master` version it _ ## Managing front-ends through Admin Dashboard -Open up Admin Dashboard (gauge icon in top bar, same as where link to AdminFE was), switch to "Front-ends" tab. -IMAGE HERE +Open up Admin Dashboard (gauge icon in top bar, same as where link to AdminFE was),__ +![location of Admin Dashboard icon](../assets/admin_dash_location.png) +switch to "Front-ends" tab. +![screenshot of Front-ends tab](../assets/frontends_tab.png) This page is designed to be self-explanatory and easy to use, while avoiding issues and pitfalls of AdminFE, but it's also early in development, everything is subject to change. -!!! bug - As of PleromaFE 2.6.0 there is no feedback on whether frontend is installing, installed or failed to install, this will be fixed in PleromaFE 2.6.1. - !!! warning This goes without saying, but if you set default frontend to anything except >2.6.0 version of PleromaFE you'll lose the access to Admin Dashboard and will have to use AdminFE to get it back. See below on how to use AdminFE. @@ -37,8 +36,9 @@ There is also no way to tell if there is an update available or not, for now you ## Using AdminFE to manage frontends -Access AdminFE either directly by going to `/pleroma/admin` of your instance or by opening Admin Dashboard and clicking the link below -IMAGE HERE +Access AdminFE either directly by going to `/pleroma/admin` of your instance or by opening Admin Dashboard and clicking the link at the bottom of the window +![link to open old AdminFE](../assets/old_adminfe_link.png) + Go to Settings -> Frontend. @@ -53,7 +53,7 @@ At the very top of the page there's a list of available frontends and button to **Available Frontends** section lets you _install_ frontends but **NOT** update/reinstall them. It's only useful for installing a frontend once. Due to aforementioned bug, preferred way of installing frontends in AdminFE is by clicking the "Install another frontend" -IMAGE HERE +![screenshot of admin-fe with instructions on how to install a frontend](../assets/way_to_install_frontends.png) and filling in the fields. Unfortunately AdminFE does not provide the raw data necessary for you to fill those fields, so your best bet is to see what backend returns in browser's devtools or refer to the [source code](https://git.pleroma.social/pleroma/pleroma/-/blob/develop/config/config.exs?ref_type=heads#L742-791). For the most part, only **Name**, **Ref** (i.e. version) and **Build URL** fields are required, although some frontends might also require **Build Directory** to work. For pleroma-fe you can use either `master` or `develop` refs, or potentially any ref in GitLab that has artifacts for `build` job, but that's outside scope of this document. @@ -61,7 +61,7 @@ For pleroma-fe you can use either `master` or `develop` refs, or potentially any ### Selecting default frontend Scroll page waaaaay down, search for "Frontends" section, subtitled "Installed frontends management", change the name and reference of the "Primary" frontend. -IMAGE HERE +![screenshot of admin-fe with instructions on how to install a frontend](../assets/primary_frontend_section.png) !!! danger diff --git a/docs/assets/admin_dash_location.png b/docs/assets/admin_dash_location.png new file mode 100644 index 000000000..4e1d110e7 Binary files /dev/null and b/docs/assets/admin_dash_location.png differ diff --git a/docs/assets/frontends_tab.png b/docs/assets/frontends_tab.png new file mode 100644 index 000000000..f7c66adab Binary files /dev/null and b/docs/assets/frontends_tab.png differ diff --git a/docs/assets/old_adminfe_link.png b/docs/assets/old_adminfe_link.png new file mode 100644 index 000000000..5ea6a486c Binary files /dev/null and b/docs/assets/old_adminfe_link.png differ diff --git a/docs/assets/primary_frontend_section.png b/docs/assets/primary_frontend_section.png new file mode 100644 index 000000000..14c3de41b Binary files /dev/null and b/docs/assets/primary_frontend_section.png differ diff --git a/docs/assets/way_to_install_frontends.png b/docs/assets/way_to_install_frontends.png new file mode 100644 index 000000000..a90ff2b5d Binary files /dev/null and b/docs/assets/way_to_install_frontends.png differ -- cgit v1.2.3 From 10525ac7f8ed4e3882a21d6cb3f1a7acfabc0674 Mon Sep 17 00:00:00 2001 From: Lain Soykaf Date: Tue, 28 Nov 2023 15:21:34 +0400 Subject: Docs: Remove rust references --- docs/installation/alpine_linux_en.md | 2 +- docs/installation/arch_linux_en.md | 1 - docs/installation/debian_based_en.md | 2 +- docs/installation/debian_based_jp.md | 1 - docs/installation/freebsd_en.md | 2 +- 5 files changed, 3 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/installation/alpine_linux_en.md b/docs/installation/alpine_linux_en.md index 9794833a3..7154bca48 100644 --- a/docs/installation/alpine_linux_en.md +++ b/docs/installation/alpine_linux_en.md @@ -28,7 +28,7 @@ sudo apk upgrade * Install some tools, which are needed later: ```shell -sudo apk add git build-base cmake file-dev rust +sudo apk add git build-base cmake file-dev ``` ### Install Elixir and Erlang diff --git a/docs/installation/arch_linux_en.md b/docs/installation/arch_linux_en.md index dbfbf6bf8..f7d722ef9 100644 --- a/docs/installation/arch_linux_en.md +++ b/docs/installation/arch_linux_en.md @@ -14,7 +14,6 @@ This guide will assume that you have administrative rights, either as root or a * `base-devel` * `cmake` * `file` -* `rust` #### Optional packages used in this guide diff --git a/docs/installation/debian_based_en.md b/docs/installation/debian_based_en.md index 44c93e1ef..b61e4addd 100644 --- a/docs/installation/debian_based_en.md +++ b/docs/installation/debian_based_en.md @@ -20,7 +20,7 @@ sudo apt full-upgrade * Install some of the above mentioned programs: ```shell -sudo apt install git build-essential postgresql postgresql-contrib cmake libmagic-dev rust +sudo apt install git build-essential postgresql postgresql-contrib cmake libmagic-dev ``` ### Install Elixir and Erlang diff --git a/docs/installation/debian_based_jp.md b/docs/installation/debian_based_jp.md index 43902c987..1424ad7f4 100644 --- a/docs/installation/debian_based_jp.md +++ b/docs/installation/debian_based_jp.md @@ -21,7 +21,6 @@ Note: This article is potentially outdated because at this time we may not have - `build-essential` - `cmake` - `libmagic-dev` -- `rust` #### このガイドで利用している追加パッケージ diff --git a/docs/installation/freebsd_en.md b/docs/installation/freebsd_en.md index b88853dd1..02513daf2 100644 --- a/docs/installation/freebsd_en.md +++ b/docs/installation/freebsd_en.md @@ -9,7 +9,7 @@ This document was written for FreeBSD 12.1, but should be work on future release This assumes the target system has `pkg(8)`. ``` -# pkg install elixir postgresql12-server postgresql12-client postgresql12-contrib git-lite sudo nginx gmake acme.sh cmake rust vips +# pkg install elixir postgresql12-server postgresql12-client postgresql12-contrib git-lite sudo nginx gmake acme.sh cmake vips ``` Copy the rc.d scripts to the right directory: -- cgit v1.2.3 From 086ba59d0346be870dc7df2660fbb55666bf0af7 Mon Sep 17 00:00:00 2001 From: "Haelwenn (lanodan) Monnier" Date: Sat, 16 Dec 2023 18:56:46 +0100 Subject: HTTPSignaturePlug: Add :authorized_fetch_mode_exceptions --- docs/configuration/cheatsheet.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index a4cae4dbb..06933ba76 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -279,6 +279,7 @@ Notes: * `deny_follow_blocked`: Whether to disallow following an account that has blocked the user in question * `sign_object_fetches`: Sign object fetches with HTTP signatures * `authorized_fetch_mode`: Require HTTP signatures for AP fetches +* `authorized_fetch_mode_exceptions`: List of IPs (CIDR format accepted) to exempt from HTTP Signatures requirement (for example to allow debugging, you shouldn't otherwise need this) ## Pleroma.User -- cgit v1.2.3 From bf57fd82bb3accd369b9bdb605e24c96134b18a9 Mon Sep 17 00:00:00 2001 From: Mark Felder Date: Wed, 20 Dec 2023 14:11:52 -0500 Subject: Clarify location of test.secret.exs file --- docs/development/setting_up_pleroma_dev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/development/setting_up_pleroma_dev.md b/docs/development/setting_up_pleroma_dev.md index 8da761d62..ddf04cab1 100644 --- a/docs/development/setting_up_pleroma_dev.md +++ b/docs/development/setting_up_pleroma_dev.md @@ -38,7 +38,7 @@ config :logger, :console, ## Testing -1. Create a `test.secret.exs` file with the content as shown below +1. Create a `config/test.secret.exs` file with the content as shown below 2. Create the database user and test database. 1. You can use the `config/setup_db.psql` as a template. Copy the file if you want and change the database name, user and password to the values for the test-database (e.g. 'pleroma_local_test' for database and user). Then run this file like you did during installation. 2. The tests will try to create the Database, so we'll have to allow our test-database user to create databases, `sudo -Hu postgres psql -c "ALTER USER pleroma_local_test WITH CREATEDB;"` -- cgit v1.2.3 From 017e35fbf128d47c033275a70b76b72f24d7c754 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?marcin=20miko=C5=82ajczak?= Date: Thu, 28 Dec 2023 00:15:32 +0100 Subject: Fix some more typos MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: marcin mikołajczak --- docs/administration/CLI_tasks/config.md | 4 ++-- docs/administration/backup.md | 2 +- docs/configuration/cheatsheet.md | 8 ++++---- docs/configuration/custom_emoji.md | 2 +- docs/configuration/i2p.md | 2 +- docs/configuration/onion_federation.md | 2 +- docs/configuration/optimizing_beam.md | 2 +- docs/configuration/postgresql.md | 2 +- docs/configuration/search.md | 4 ++-- docs/development/API/admin_api.md | 10 +++++----- docs/development/API/pleroma_api.md | 2 +- docs/development/ap_extensions.md | 6 +++--- docs/development/setting_up_pleroma_dev.md | 2 +- docs/installation/gentoo_en.md | 4 ++-- docs/installation/gentoo_otp_en.md | 2 +- docs/installation/openbsd_en.md | 4 ++-- docs/installation/otp_en.md | 2 +- 17 files changed, 30 insertions(+), 30 deletions(-) (limited to 'docs') diff --git a/docs/administration/CLI_tasks/config.md b/docs/administration/CLI_tasks/config.md index fc9f3cbd5..7c167ec5d 100644 --- a/docs/administration/CLI_tasks/config.md +++ b/docs/administration/CLI_tasks/config.md @@ -1,4 +1,4 @@ -# Transfering the config to/from the database +# Transferring the config to/from the database {! backend/administration/CLI_tasks/general_cli_task_info.include !} @@ -34,7 +34,7 @@ Options: -- `` - where to save migrated config. E.g. `--path=/tmp`. If file saved into non standart folder, you must manually copy file into directory where Pleroma can read it. For OTP install path will be `PLEROMA_CONFIG_PATH` or `/etc/pleroma`. For installation from source - `config` directory in the pleroma folder. +- `` - where to save migrated config. E.g. `--path=/tmp`. If file saved into non-standard folder, you must manually copy file into directory where Pleroma can read it. For OTP install path will be `PLEROMA_CONFIG_PATH` or `/etc/pleroma`. For installation from source - `config` directory in the pleroma folder. - `` - environment, for which is migrated config. By default is `prod`. - To delete transferred settings from database optional flag `-d` can be used diff --git a/docs/administration/backup.md b/docs/administration/backup.md index 5f279ab97..93325e702 100644 --- a/docs/administration/backup.md +++ b/docs/administration/backup.md @@ -31,7 +31,7 @@ 1. Optionally you can remove the users of your instance. This will trigger delete requests for their accounts and posts. Note that this is 'best effort' and doesn't mean that all traces of your instance will be gone from the fediverse. * You can do this from the admin-FE where you can select all local users and delete the accounts using the *Moderate multiple users* dropdown. - * You can also list local users and delete them individualy using the CLI tasks for [Managing users](./CLI_tasks/user.md). + * You can also list local users and delete them individually using the CLI tasks for [Managing users](./CLI_tasks/user.md). 2. Stop the Pleroma service `systemctl stop pleroma` 3. Disable pleroma from systemd `systemctl disable pleroma` 4. Remove the files and folders you created during installation (see installation guide). This includes the pleroma, nginx and systemd files and folders. diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index a4cae4dbb..7bba7b26e 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -154,7 +154,7 @@ To add configuration to your config file, you can copy it from the base config. * `Pleroma.Web.ActivityPub.MRF.MentionPolicy`: Drops posts mentioning configurable users. (See [`:mrf_mention`](#mrf_mention)). * `Pleroma.Web.ActivityPub.MRF.VocabularyPolicy`: Restricts activities to a configured set of vocabulary. (See [`:mrf_vocabulary`](#mrf_vocabulary)). * `Pleroma.Web.ActivityPub.MRF.ObjectAgePolicy`: Rejects or delists posts based on their age when received. (See [`:mrf_object_age`](#mrf_object_age)). - * `Pleroma.Web.ActivityPub.MRF.ActivityExpirationPolicy`: Sets a default expiration on all posts made by users of the local instance. Requires `Pleroma.Workers.PurgeExpiredActivity` to be enabled for processing the scheduled delections. + * `Pleroma.Web.ActivityPub.MRF.ActivityExpirationPolicy`: Sets a default expiration on all posts made by users of the local instance. Requires `Pleroma.Workers.PurgeExpiredActivity` to be enabled for processing the scheduled deletions. * `Pleroma.Web.ActivityPub.MRF.ForceBotUnlistedPolicy`: Makes all bot posts to disappear from public timelines. * `Pleroma.Web.ActivityPub.MRF.FollowBotPolicy`: Automatically follows newly discovered users from the specified bot account. Local accounts, locked accounts, and users with "#nobot" in their bio are respected and excluded from being followed. * `Pleroma.Web.ActivityPub.MRF.AntiFollowbotPolicy`: Drops follow requests from followbots. Users can still allow bots to follow them by first following the bot. @@ -506,7 +506,7 @@ config :pleroma, :rate_limit, Means that: 1. In 60 seconds, 15 authentication attempts can be performed from the same IP address. -2. In 1 second, 10 search requests can be performed from the same IP adress by unauthenticated users, while authenticated users can perform 30 search requests per second. +2. In 1 second, 10 search requests can be performed from the same IP address by unauthenticated users, while authenticated users can perform 30 search requests per second. Supported rate limiters: @@ -1081,7 +1081,7 @@ config :pleroma, Pleroma.Formatter, ## :configurable_from_database -Boolean, enables/disables in-database configuration. Read [Transfering the config to/from the database](../administration/CLI_tasks/config.md) for more information. +Boolean, enables/disables in-database configuration. Read [Transferring the config to/from the database](../administration/CLI_tasks/config.md) for more information. ## :database_config_whitelist @@ -1142,7 +1142,7 @@ Control favicons for instances. !!! note Requires enabled email -* `:purge_after_days` an integer, remove backup achives after N days. +* `:purge_after_days` an integer, remove backup achieves after N days. * `:limit_days` an integer, limit user to export not more often than once per N days. * `:dir` a string with a path to backup temporary directory or `nil` to let Pleroma choose temporary directory in the following order: 1. the directory named by the TMPDIR environment variable diff --git a/docs/configuration/custom_emoji.md b/docs/configuration/custom_emoji.md index 1648840fd..19250cf80 100644 --- a/docs/configuration/custom_emoji.md +++ b/docs/configuration/custom_emoji.md @@ -29,7 +29,7 @@ foo, /emoji/custom/foo.png The files should be PNG (APNG is okay with `.png` for `image/png` Content-type) and under 50kb for compatibility with mastodon. -Default file extentions and locations for emojis are set in `config.exs`. To use different locations or file-extentions, add the `shortcode_globs` to your secrets file (`prod.secret.exs` or `dev.secret.exs`) and edit it. Note that not all fediverse-software will show emojis with other file extentions: +Default file extensions and locations for emojis are set in `config.exs`. To use different locations or file-extensions, add the `shortcode_globs` to your secrets file (`prod.secret.exs` or `dev.secret.exs`) and edit it. Note that not all fediverse-software will show emojis with other file extensions: ```elixir config :pleroma, :emoji, shortcode_globs: ["/emoji/custom/**/*.png", "/emoji/custom/**/*.gif"] ``` diff --git a/docs/configuration/i2p.md b/docs/configuration/i2p.md index 8c5207d67..17dd9b0cb 100644 --- a/docs/configuration/i2p.md +++ b/docs/configuration/i2p.md @@ -1,4 +1,4 @@ -# I2P Federation and Accessability +# I2P Federation and Accessibility This guide is going to focus on the Pleroma federation aspect. The actual installation is neatly explained in the official documentation, and more likely to remain up-to-date. It might be added to this guide if there will be a need for that. diff --git a/docs/configuration/onion_federation.md b/docs/configuration/onion_federation.md index 37673211a..8a8137251 100644 --- a/docs/configuration/onion_federation.md +++ b/docs/configuration/onion_federation.md @@ -29,7 +29,7 @@ HiddenServiceDir /var/lib/tor/pleroma_hidden_service/ HiddenServicePort 80 127.0.0.1:8099 HiddenServiceVersion 3 # Remove if Tor version is below 0.3 ( tor --version ) ``` -Restart Tor to generate an adress: +Restart Tor to generate an address: ``` systemctl restart tor@default.service ``` diff --git a/docs/configuration/optimizing_beam.md b/docs/configuration/optimizing_beam.md index e336bd36c..5e81cd003 100644 --- a/docs/configuration/optimizing_beam.md +++ b/docs/configuration/optimizing_beam.md @@ -1,6 +1,6 @@ # Optimizing the BEAM -Pleroma is built upon the Erlang/OTP VM known as BEAM. The BEAM VM is highly optimized for latency, but this has drawbacks in environments without dedicated hardware. One of the tricks used by the BEAM VM is [busy waiting](https://en.wikipedia.org/wiki/Busy_waiting). This allows the application to pretend to be busy working so the OS kernel does not pause the application process and switch to another process waiting for the CPU to execute its workload. It does this by spinning for a period of time which inflates the apparent CPU usage of the application so it is immediately ready to execute another task. This can be observed with utilities like **top(1)** which will show consistently high CPU usage for the process. Switching between procesess is a rather expensive operation and also clears CPU caches further affecting latency and performance. The goal of busy waiting is to avoid this penalty. +Pleroma is built upon the Erlang/OTP VM known as BEAM. The BEAM VM is highly optimized for latency, but this has drawbacks in environments without dedicated hardware. One of the tricks used by the BEAM VM is [busy waiting](https://en.wikipedia.org/wiki/Busy_waiting). This allows the application to pretend to be busy working so the OS kernel does not pause the application process and switch to another process waiting for the CPU to execute its workload. It does this by spinning for a period of time which inflates the apparent CPU usage of the application so it is immediately ready to execute another task. This can be observed with utilities like **top(1)** which will show consistently high CPU usage for the process. Switching between processes is a rather expensive operation and also clears CPU caches further affecting latency and performance. The goal of busy waiting is to avoid this penalty. This strategy is very successful in making a performant and responsive application, but is not desirable on Virtual Machines or hardware with few CPU cores. Pleroma instances are often deployed on the same server as the required PostgreSQL database which can lead to situations where the Pleroma application is holding the CPU in a busy-wait loop and as a result the database cannot process requests in a timely manner. The fewer CPUs available, the more this problem is exacerbated. The latency is further amplified by the OS being installed on a Virtual Machine as the Hypervisor uses CPU time-slicing to pause the entire OS and switch between other tasks. diff --git a/docs/configuration/postgresql.md b/docs/configuration/postgresql.md index e251eb83b..56f1c60dc 100644 --- a/docs/configuration/postgresql.md +++ b/docs/configuration/postgresql.md @@ -22,7 +22,7 @@ config :pleroma, Pleroma.Repo, ] ``` -A more detailed explaination of the issue can be found at . +A more detailed explanation of the issue can be found at . ## Example configurations diff --git a/docs/configuration/search.md b/docs/configuration/search.md index f131948a7..0316c9bf4 100644 --- a/docs/configuration/search.md +++ b/docs/configuration/search.md @@ -38,7 +38,7 @@ indexes faster when it can process many posts in a single batch. Information about setting up meilisearch can be found in the [official documentation](https://docs.meilisearch.com/learn/getting_started/installation.html). You probably want to start it with `MEILI_NO_ANALYTICS=true` environment variable to disable analytics. -At least version 0.25.0 is required, but you are strongly adviced to use at least 0.26.0, as it introduces +At least version 0.25.0 is required, but you are strongly advised to use at least 0.26.0, as it introduces the `--enable-auto-batching` option which drastically improves performance. Without this option, the search is hardly usable on a somewhat big instance. @@ -61,7 +61,7 @@ You will see a "Default Admin API Key", this is the key you actually put into yo ### Initial indexing -After setting up the configuration, you'll want to index all of your already existsing posts. Only public posts are indexed. You'll only +After setting up the configuration, you'll want to index all of your already existing posts. Only public posts are indexed. You'll only have to do it one time, but it might take a while, depending on the amount of posts your instance has seen. This is also a fairly RAM consuming process for `meilisearch`, and it will take a lot of RAM when running if you have a lot of posts (seems to be around 5G for ~1.2 million posts while idle and up to 7G while indexing initially, but your experience may be different). diff --git a/docs/development/API/admin_api.md b/docs/development/API/admin_api.md index 7d31ee262..182a760fa 100644 --- a/docs/development/API/admin_api.md +++ b/docs/development/API/admin_api.md @@ -303,7 +303,7 @@ Removes the user(s) from follower recommendations. ## `GET /api/v1/pleroma/admin/users/:nickname_or_id` -### Retrive the details of a user +### Retrieve the details of a user - Params: - `nickname` or `id` @@ -313,7 +313,7 @@ Removes the user(s) from follower recommendations. ## `GET /api/v1/pleroma/admin/users/:nickname_or_id/statuses` -### Retrive user's latest statuses +### Retrieve user's latest statuses - Params: - `nickname` or `id` @@ -337,7 +337,7 @@ Removes the user(s) from follower recommendations. ## `GET /api/v1/pleroma/admin/instances/:instance/statuses` -### Retrive instance's latest statuses +### Retrieve instance's latest statuses - Params: - `instance`: instance name @@ -377,7 +377,7 @@ It may take some time. ## `GET /api/v1/pleroma/admin/statuses` -### Retrives all latest statuses +### Retrieves all latest statuses - Params: - *optional* `page_size`: number of statuses to return (default is `20`) @@ -541,7 +541,7 @@ Response: ## `PATCH /api/v1/pleroma/admin/users/force_password_reset` -### Force passord reset for a user with a given nickname +### Force password reset for a user with a given nickname - Params: - `nicknames` diff --git a/docs/development/API/pleroma_api.md b/docs/development/API/pleroma_api.md index bd0e07f9e..71cd0166f 100644 --- a/docs/development/API/pleroma_api.md +++ b/docs/development/API/pleroma_api.md @@ -382,7 +382,7 @@ Pleroma Conversations have the same general structure that Mastodon Conversation Conversations have the additional field `recipients` under the `pleroma` key. This holds a list of all the accounts that will receive a message in this conversation. -The status posting endpoint takes an additional parameter, `in_reply_to_conversation_id`, which, when set, will set the visiblity to direct and address only the people who are the recipients of that Conversation. +The status posting endpoint takes an additional parameter, `in_reply_to_conversation_id`, which, when set, will set the visibility to direct and address only the people who are the recipients of that Conversation. ⚠ Conversation IDs can be found in direct messages with the `pleroma.direct_conversation_id` key, do not confuse it with `pleroma.conversation_id`. diff --git a/docs/development/ap_extensions.md b/docs/development/ap_extensions.md index 3d1caeb3e..75c8a7b54 100644 --- a/docs/development/ap_extensions.md +++ b/docs/development/ap_extensions.md @@ -20,16 +20,16 @@ Content-Type: multipart/form-data Parameters: - (required) `file`: The file being uploaded -- (optionnal) `description`: A plain-text description of the media, for accessibility purposes. +- (optional) `description`: A plain-text description of the media, for accessibility purposes. Response: HTTP 201 Created with the object into the body, no `Location` header provided as it doesn't have an `id` -The object given in the reponse should then be inserted into an Object's `attachment` field. +The object given in the response should then be inserted into an Object's `attachment` field. ## ChatMessages `ChatMessage`s are the messages sent in 1-on-1 chats. They are similar to -`Note`s, but the addresing is done by having a single AP actor in the `to` +`Note`s, but the addressing is done by having a single AP actor in the `to` field. Addressing multiple actors is not allowed. These messages are always private, there is no public version of them. They are created with a `Create` activity. diff --git a/docs/development/setting_up_pleroma_dev.md b/docs/development/setting_up_pleroma_dev.md index ddf04cab1..24f358e4a 100644 --- a/docs/development/setting_up_pleroma_dev.md +++ b/docs/development/setting_up_pleroma_dev.md @@ -15,7 +15,7 @@ Pleroma requires some adjustments from the defaults for running the instance loc 2. Change the dev.secret.exs * Change the scheme in `config :pleroma, Pleroma.Web.Endpoint` to http (see examples below) * If you want to change other settings, you can do that too -3. You can now start the server `mix phx.server`. Once it's build and started, you can access the instance on `http://:` (e.g.http://localhost:4000 ) and should be able to do everything locally you normaly can. +3. You can now start the server `mix phx.server`. Once it's build and started, you can access the instance on `http://:` (e.g.http://localhost:4000 ) and should be able to do everything locally you normally can. Example config to change the scheme to http. Change the port if you want to run on another port. ```elixir diff --git a/docs/installation/gentoo_en.md b/docs/installation/gentoo_en.md index 87128d6f6..dc47d27f8 100644 --- a/docs/installation/gentoo_en.md +++ b/docs/installation/gentoo_en.md @@ -59,7 +59,7 @@ Gentoo quite pointedly does not come with a cron daemon installed, and as such i If you would not like to install the optional packages, remove them from this line. -If you're running this from a low-powered virtual machine, it should work though it will take some time. There were no issues on a VPS with a single core and 1GB of RAM; if you are using an even more limited device and run into issues, you can try creating a swapfile or use a more powerful machine running Gentoo to [cross build](https://wiki.gentoo.org/wiki/Cross_build_environment). If you have a wait ahead of you, now would be a good time to take a break, strech a bit, refresh your beverage of choice and/or get a snack, and reply to Arch users' posts with "I use Gentoo btw" as we do. +If you're running this from a low-powered virtual machine, it should work though it will take some time. There were no issues on a VPS with a single core and 1GB of RAM; if you are using an even more limited device and run into issues, you can try creating a swapfile or use a more powerful machine running Gentoo to [cross build](https://wiki.gentoo.org/wiki/Cross_build_environment). If you have a wait ahead of you, now would be a good time to take a break, stretch a bit, refresh your beverage of choice and/or get a snack, and reply to Arch users' posts with "I use Gentoo btw" as we do. ### Install PostgreSQL @@ -104,7 +104,7 @@ Not only does this make it much easier to deploy changes you make, as you can co * Add a new system user for the Pleroma service and set up default directories: -Remove `,wheel` if you do not want this user to be able to use `sudo`, however note that being able to `sudo` as the `pleroma` user will make finishing the insallation and common maintenence tasks somewhat easier: +Remove `,wheel` if you do not want this user to be able to use `sudo`, however note that being able to `sudo` as the `pleroma` user will make finishing the installation and common maintenance tasks somewhat easier: ```shell # useradd -m -G users,wheel -s /bin/bash pleroma diff --git a/docs/installation/gentoo_otp_en.md b/docs/installation/gentoo_otp_en.md index 4fafc0c17..20d8835da 100644 --- a/docs/installation/gentoo_otp_en.md +++ b/docs/installation/gentoo_otp_en.md @@ -49,7 +49,7 @@ Gentoo quite pointedly does not come with a cron daemon installed, and as such i If you would not like to install the optional packages, remove them from this line. -If you're running this from a low-powered virtual machine, it should work though it will take some time. There were no issues on a VPS with a single core and 1GB of RAM; if you are using an even more limited device and run into issues, you can try creating a swapfile or use a more powerful machine running Gentoo to [cross build](https://wiki.gentoo.org/wiki/Cross_build_environment). If you have a wait ahead of you, now would be a good time to take a break, strech a bit, refresh your beverage of choice and/or get a snack, and reply to Arch users' posts with "I use Gentoo btw" as we do. +If you're running this from a low-powered virtual machine, it should work though it will take some time. There were no issues on a VPS with a single core and 1GB of RAM; if you are using an even more limited device and run into issues, you can try creating a swapfile or use a more powerful machine running Gentoo to [cross build](https://wiki.gentoo.org/wiki/Cross_build_environment). If you have a wait ahead of you, now would be a good time to take a break, stretch a bit, refresh your beverage of choice and/or get a snack, and reply to Arch users' posts with "I use Gentoo btw" as we do. ### Setup PostgreSQL diff --git a/docs/installation/openbsd_en.md b/docs/installation/openbsd_en.md index 9e7e040f5..e58e144d2 100644 --- a/docs/installation/openbsd_en.md +++ b/docs/installation/openbsd_en.md @@ -62,7 +62,7 @@ rcctl start postgresql To check that it started properly and didn't fail right after starting, you can run `ps aux | grep postgres`, there should be multiple lines of output. #### httpd -httpd will have three fuctions: +httpd will have three functions: * redirect requests trying to reach the instance over http to the https URL * serve a robots.txt file @@ -225,7 +225,7 @@ pass in quick on $if inet6 proto icmp6 to ($if) icmp6-type { echoreq unreach par pass in quick on $if proto tcp to ($if) port { http https } # relayd/httpd pass in quick on $if proto tcp from $authorized_ssh_clients to ($if) port ssh ``` -Replace ** by your server's network interface name (which you can get with ifconfig). Consider replacing the content of the authorized\_ssh\_clients macro by, for exemple, your home IP address, to avoid SSH connection attempts from bots. +Replace ** by your server's network interface name (which you can get with ifconfig). Consider replacing the content of the authorized\_ssh\_clients macro by, for example, your home IP address, to avoid SSH connection attempts from bots. Check pf's configuration by running `pfctl -nf /etc/pf.conf`, load it with `pfctl -f /etc/pf.conf` and enable pf at boot with `rcctl enable pf`. diff --git a/docs/installation/otp_en.md b/docs/installation/otp_en.md index a69b2fe7a..86efa27f8 100644 --- a/docs/installation/otp_en.md +++ b/docs/installation/otp_en.md @@ -238,7 +238,7 @@ At this point if you open your (sub)domain in a browser you should see a 502 err systemctl enable pleroma ``` -If everything worked, you should see Pleroma-FE when visiting your domain. If that didn't happen, try reviewing the installation steps, starting Pleroma in the foreground and seeing if there are any errrors. +If everything worked, you should see Pleroma-FE when visiting your domain. If that didn't happen, try reviewing the installation steps, starting Pleroma in the foreground and seeing if there are any errors. 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, you can also [file an issue on our Gitlab](https://git.pleroma.social/pleroma/pleroma-support/issues/new). -- cgit v1.2.3 From ddb9e90c405369496fdf9e6dfed593eff8d5dc5c Mon Sep 17 00:00:00 2001 From: Mark Felder Date: Thu, 28 Dec 2023 15:59:25 -0500 Subject: Update minimum elixir version found in various docs --- docs/installation/debian_based_jp.md | 2 +- docs/installation/generic_dependencies.include | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/installation/debian_based_jp.md b/docs/installation/debian_based_jp.md index 1424ad7f4..502eefaf8 100644 --- a/docs/installation/debian_based_jp.md +++ b/docs/installation/debian_based_jp.md @@ -14,7 +14,7 @@ Note: This article is potentially outdated because at this time we may not have - PostgreSQL 9.6以上 (Ubuntu16.04では9.5しか提供されていないので，[](https://www.postgresql.org/download/linux/ubuntu/)こちらから新しいバージョンを入手してください) - `postgresql-contrib` 9.6以上 (同上) -- Elixir 1.8 以上 ([Debianのリポジトリからインストールしないこと！！！ ここからインストールすること！](https://elixir-lang.org/install.html#unix-and-unix-like)。または [asdf](https://github.com/asdf-vm/asdf) をpleromaユーザーでインストールしてください) +- Elixir 1.13 以上 ([Debianのリポジトリからインストールしないこと！！！ ここからインストールすること！](https://elixir-lang.org/install.html#unix-and-unix-like)。または [asdf](https://github.com/asdf-vm/asdf) をpleromaユーザーでインストールしてください) - `erlang-dev` - `erlang-nox` - `git` diff --git a/docs/installation/generic_dependencies.include b/docs/installation/generic_dependencies.include index 3365a36a8..e0cfd3264 100644 --- a/docs/installation/generic_dependencies.include +++ b/docs/installation/generic_dependencies.include @@ -1,7 +1,7 @@ ## Required dependencies * PostgreSQL >=9.6 -* Elixir >=1.11.0 <1.15 +* Elixir >=1.13.0 <1.15 * Erlang OTP >=22.2.0 <26 * git * file / libmagic -- cgit v1.2.3 From 63a74f7b6dcfd8b5498a98d1fd0a08b7f0cfdd26 Mon Sep 17 00:00:00 2001 From: Mark Felder Date: Fri, 29 Dec 2023 23:22:31 -0500 Subject: Support for Erlang OTP 26 --- docs/installation/generic_dependencies.include | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/installation/generic_dependencies.include b/docs/installation/generic_dependencies.include index 3365a36a8..56274a3f0 100644 --- a/docs/installation/generic_dependencies.include +++ b/docs/installation/generic_dependencies.include @@ -2,7 +2,7 @@ * PostgreSQL >=9.6 * Elixir >=1.11.0 <1.15 -* Erlang OTP >=22.2.0 <26 +* Erlang OTP >=22.2.0 * git * file / libmagic * gcc or clang -- cgit v1.2.3 From 355487041a610a2834eebca520660b74a667df06 Mon Sep 17 00:00:00 2001 From: Haelwenn Date: Tue, 16 Jan 2024 16:21:23 +0000 Subject: We are unsure if OTP27 will bring more breaking changes --- docs/installation/generic_dependencies.include | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/installation/generic_dependencies.include b/docs/installation/generic_dependencies.include index 56274a3f0..aebf21e7c 100644 --- a/docs/installation/generic_dependencies.include +++ b/docs/installation/generic_dependencies.include @@ -2,7 +2,7 @@ * PostgreSQL >=9.6 * Elixir >=1.11.0 <1.15 -* Erlang OTP >=22.2.0 +* Erlang OTP >=22.2.0 (supported: <27) * git * file / libmagic * gcc or clang -- cgit v1.2.3 From b39403a48fdb861b905bea16febba6d1660bb8df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?marcin=20miko=C5=82ajczak?= Date: Wed, 17 Jan 2024 17:12:40 +0100 Subject: Update API docs for my changes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: marcin mikołajczak --- .../API/differences_in_mastoapi_responses.md | 13 ++++++++-- docs/development/API/pleroma_api.md | 28 +++++++++++++++++++++- 2 files changed, 38 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/development/API/differences_in_mastoapi_responses.md b/docs/development/API/differences_in_mastoapi_responses.md index 48a9c104c..2937b2301 100644 --- a/docs/development/API/differences_in_mastoapi_responses.md +++ b/docs/development/API/differences_in_mastoapi_responses.md @@ -1,6 +1,6 @@ # Differences in Mastodon API responses from vanilla Mastodon -A Pleroma instance can be identified by " (compatible; Pleroma )" present in `version` field in response from `/api/v1/instance` +A Pleroma instance can be identified by " (compatible; Pleroma )" present in `version` field in response from `/api/v1/instance` and `/api/v2/instance` ## Flake IDs @@ -39,6 +39,7 @@ Has these additional fields under the `pleroma` object: - `emoji_reactions`: A list with emoji / reaction maps. The format is `{name: "☕", count: 1, me: true}`. Contains no information about the reacting users, for that use the `/statuses/:id/reactions` endpoint. - `parent_visible`: If the parent of this post is visible to the user or not. - `pinned_at`: a datetime (iso8601) when status was pinned, `null` otherwise. +- `quotes_count`: the count of status quotes. The `GET /api/v1/statuses/:id/source` endpoint additionally has the following attributes: @@ -304,19 +305,27 @@ Has these additional parameters (which are the same as in Pleroma-API): `GET /api/v1/instance` has additional fields - `max_toot_chars`: The maximum characters per post +- `max_media_attachments`: Maximum number of post media attachments - `chat_limit`: The maximum characters per chat message - `description_limit`: The maximum characters per image description - `poll_limits`: The limits of polls +- `shout_limit`: The maximum characters per Shoutbox message - `upload_limit`: The maximum upload file size - `avatar_upload_limit`: The same for avatars - `background_upload_limit`: The same for backgrounds - `banner_upload_limit`: The same for banners - `background_image`: A background image that frontends can use +- `pleroma.metadata.account_activation_required`: Whether users are required to confirm their emails before signing in +- `pleroma.metadata.birthday_required`: Whether users are required to provide their birth day when signing in +- `pleroma.metadata.birthday_min_age`: The minimum user age (in days) - `pleroma.metadata.features`: A list of supported features - `pleroma.metadata.federation`: The federation restrictions of this instance - `pleroma.metadata.fields_limits`: A list of values detailing the length and count limitation for various instance-configurable fields. - `pleroma.metadata.post_formats`: A list of the allowed post format types -- `vapid_public_key`: The public key needed for push messages +- `pleroma.stats.mau`: Monthly active user count +- `pleroma.vapid_public_key`: The public key needed for push messages + +In, `GET /api/v2/instance` Pleroma-specific fields are all moved into `pleroma` object. `max_toot_chars`, `poll_limits` and `upload_limit` are replaced with their MastoAPI counterparts. ## Push Subscription diff --git a/docs/development/API/pleroma_api.md b/docs/development/API/pleroma_api.md index 71cd0166f..060af5c14 100644 --- a/docs/development/API/pleroma_api.md +++ b/docs/development/API/pleroma_api.md @@ -129,7 +129,7 @@ The `/api/v1/pleroma/*` path is backwards compatible with `/api/pleroma/*` (`/ap * method: `GET` * Authentication: required * OAuth scope: `write:security` -* Response: JSON. Returns `{"codes": codes}`when successful, otherwise HTTP 422 `{"error": "[error message]"}` +* Response: JSON. Returns `{"codes": codes}` when successful, otherwise HTTP 422 `{"error": "[error message]"}` ## `/api/v1/pleroma/admin/` See [Admin-API](admin_api.md) @@ -251,6 +251,15 @@ See [Admin-API](admin_api.md) ] ``` + +## `/api/v1/pleroma/accounts/:id/endorsements` +### Returns users endorsed by a user +* Method `GET` +* Authentication: not required +* Params: + * `id`: the id of the account for whom to return results +* Response: JSON, returns a list of Mastodon Account entities + ## `/api/v1/pleroma/accounts/update_*` ### Set and clear account avatar, banner, and background @@ -266,6 +275,14 @@ See [Admin-API](admin_api.md) * Authentication: not required * Response: 204 No Content +## `/api/v1/pleroma/statuses/:id/quotes` +### Gets quotes for a given status +* Method `GET` +* Authentication: not required +* Params: + * `id`: the id of the status +* Response: JSON, returns a list of Mastodon Status entities + ## `/api/v1/pleroma/mascot` ### Gets user mascot image * Method `GET` @@ -372,6 +389,15 @@ See [Admin-API](admin_api.md) * `alias`: the nickname of the alias to delete, e.g. `foo@example.org`. * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise +## `/api/v1/pleroma/remote_interaction` +## Interact with profile or status from remote account +* Metod `POST` +* Authentication: not required +* Params: + * `ap_id`: Profile or status ActivityPub ID + * `profile`: Remote profile webfinger +* Response: JSON. Returns `{"url": "[redirect url]"}` on success, `{"error": "[error message]"}` otherwise + # Pleroma Conversations Pleroma Conversations have the same general structure that Mastodon Conversations have. The behavior differs in the following ways when using these endpoints: -- cgit v1.2.3 From 90b442727e4e2e56b4b68a15172a5ef7516531df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?marcin=20miko=C5=82ajczak?= Date: Fri, 19 Jan 2024 17:53:37 +0100 Subject: Update Admin API docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: marcin mikołajczak --- docs/development/API/admin_api.md | 47 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) (limited to 'docs') diff --git a/docs/development/API/admin_api.md b/docs/development/API/admin_api.md index 7d31ee262..b8dc419e2 100644 --- a/docs/development/API/admin_api.md +++ b/docs/development/API/admin_api.md @@ -1751,3 +1751,50 @@ Note that this differs from the Mastodon API variant: Mastodon API only returns ```json {} ``` + + +## `GET /api/v1/pleroma/admin/rules` + +### List rules + +- Response: JSON, list of rules + +```json +[ + { + "id": "1", + "priority": 1, + "text": "There are no rules" + } +] +``` + +## `POST /api/v1/pleroma/admin/rules` + +### Create a rule + +- Params: + - `text`: string, required, rule content + - `priority`: integer, optional, rule ordering priority + +- Response: JSON, a single rule + +## `PATCH /api/v1/pleroma/admin/rules/:id` + +### Update a rule + +- Params: + - `text`: string, optional, rule content + - `priority`: integer, optional, rule ordering priority + +- Response: JSON, a single rule + +## `DELETE /api/v1/pleroma/admin/rules/:id` + +### Delete a rule + +- Response: JSON, empty object + +```json +{} +``` -- cgit v1.2.3 From fa02a1e634632bb672b53c244179d3088ffe8423 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?marcin=20miko=C5=82ajczak?= Date: Fri, 19 Jan 2024 18:05:46 +0100 Subject: Update MastoAPI responses docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: marcin mikołajczak --- docs/development/API/differences_in_mastoapi_responses.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/development/API/differences_in_mastoapi_responses.md b/docs/development/API/differences_in_mastoapi_responses.md index 48a9c104c..70c31272d 100644 --- a/docs/development/API/differences_in_mastoapi_responses.md +++ b/docs/development/API/differences_in_mastoapi_responses.md @@ -39,6 +39,7 @@ Has these additional fields under the `pleroma` object: - `emoji_reactions`: A list with emoji / reaction maps. The format is `{name: "☕", count: 1, me: true}`. Contains no information about the reacting users, for that use the `/statuses/:id/reactions` endpoint. - `parent_visible`: If the parent of this post is visible to the user or not. - `pinned_at`: a datetime (iso8601) when status was pinned, `null` otherwise. +- `non_anonymous`: true if the source post specifies the poll results are not anonymous. Currently only implemented by Smithereen. The `GET /api/v1/statuses/:id/source` endpoint additionally has the following attributes: -- cgit v1.2.3 From d415686bb9248e1c5b8913b7c3b96f74e9b8f230 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?marcin=20miko=C5=82ajczak?= Date: Mon, 26 Feb 2024 23:45:02 +0100 Subject: Allow to group bookmarks in folders MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: marcin mikołajczak --- .../API/differences_in_mastoapi_responses.md | 7 ++++ docs/development/API/pleroma_api.md | 46 ++++++++++++++++++++++ 2 files changed, 53 insertions(+) (limited to 'docs') diff --git a/docs/development/API/differences_in_mastoapi_responses.md b/docs/development/API/differences_in_mastoapi_responses.md index 2937b2301..d72717483 100644 --- a/docs/development/API/differences_in_mastoapi_responses.md +++ b/docs/development/API/differences_in_mastoapi_responses.md @@ -40,6 +40,7 @@ Has these additional fields under the `pleroma` object: - `parent_visible`: If the parent of this post is visible to the user or not. - `pinned_at`: a datetime (iso8601) when status was pinned, `null` otherwise. - `quotes_count`: the count of status quotes. +- `bookmark_folder`: the ID of the folder bookmark is stored within (if any). The `GET /api/v1/statuses/:id/source` endpoint additionally has the following attributes: @@ -65,6 +66,12 @@ Some apps operate under the assumption that no more than 4 attachments can be re Pleroma does not process remote images and therefore cannot include fields such as `meta` and `blurhash`. It does not support focal points or aspect ratios. The frontend is expected to handle it. +## Bookmarks + +The `GET /api/v1/bookmarks` endpoint accepts optional parameter `folder_id` for bookmark folder ID. + +The `POST /api/v1/statuses/:id/bookmark` endpoint accepts optional parameter `folder_id` for bookmark folder ID. + ## Accounts The `id` parameter can also be the `nickname` of the user. This only works in these endpoints, not the deeper nested ones for following etc. diff --git a/docs/development/API/pleroma_api.md b/docs/development/API/pleroma_api.md index 060af5c14..267dfc1ec 100644 --- a/docs/development/API/pleroma_api.md +++ b/docs/development/API/pleroma_api.md @@ -283,6 +283,52 @@ See [Admin-API](admin_api.md) * `id`: the id of the status * Response: JSON, returns a list of Mastodon Status entities +## `GET /api/v1/pleroma/bookmark_folders` +### Gets user bookmark folders +* Authentication: required + +* Response: JSON. Returns a list of bookmark folders. +* Example response: +```json +[ + { + "id": "9umDrYheeY451cQnEe", + "name": "Read later", + "emoji": "🕓", + "source": { + "emoji": "🕓" + } + } +] +``` + +## `POST /api/v1/pleroma/bookmark_folders` +### Creates a bookmark folder +* Authentication: required + +* Params: + * `name`: folder name + * `emoji`: folder emoji (optional) +* Response: JSON. Returns a single bookmark folder. + +## `PATCH /api/v1/pleroma/bookmark_folders/:id` +### Updates a bookmark folder +* Authentication: required + +* Params: + * `id`: folder id + * `name`: folder name (optional) + * `emoji`: folder emoji (optional) +* Response: JSON. Returns a single bookmark folder. + +## `DELETE /api/v1/pleroma/bookmark_folders/:id` +### Deletes a bookmark folder +* Authentication: required + +* Params: + * `id`: folder id +* Response: JSON. Returns a single bookmark folder. + ## `/api/v1/pleroma/mascot` ### Gets user mascot image * Method `GET` -- cgit v1.2.3 From 9cfa4e67b11e5a1a7d09330581383dc67fcf6fd8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?marcin=20miko=C5=82ajczak?= Date: Fri, 1 Mar 2024 18:14:31 +0100 Subject: Add ForceMention mrf MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: marcin mikołajczak --- docs/configuration/cheatsheet.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index 7bba7b26e..89a461b47 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -161,7 +161,8 @@ To add configuration to your config file, you can copy it from the base config. * `Pleroma.Web.ActivityPub.MRF.KeywordPolicy`: Rejects or removes from the federated timeline or replaces keywords. (See [`:mrf_keyword`](#mrf_keyword)). * `Pleroma.Web.ActivityPub.MRF.ForceMentionsInContent`: Forces every mentioned user to be reflected in the post content. * `Pleroma.Web.ActivityPub.MRF.InlineQuotePolicy`: Forces quote post URLs to be reflected in the message content inline. - * `Pleroma.Web.ActivityPub.MRF.QuoteToLinkTagPolicy`: Force a Link tag for posts quoting another post. (may break outgoing federation of quote posts with older Pleroma versions) + * `Pleroma.Web.ActivityPub.MRF.QuoteToLinkTagPolicy`: Force a Link tag for posts quoting another post. (may break outgoing federation of quote posts with older Pleroma versions). + * `Pleroma.Web.ActivityPub.MRF.ForceMention`: Forces posts to include a mention of the author of parent post or the author of quoted post. * `transparency`: Make the content of your Message Rewrite Facility settings public (via nodeinfo). * `transparency_exclusions`: Exclude specific instance names from MRF transparency. The use of the exclusions feature will be disclosed in nodeinfo as a boolean value. @@ -272,6 +273,10 @@ Notes: #### :mrf_inline_quote * `template`: The template to append to the post. `{url}` will be replaced with the actual link to the quoted post. Default: `RT: {url}` +#### :mrf_force_mention +* `mention_parent`: Whether to append mention of parent post author +* `mention_quoted`: Whether to append mention of parent quoted author + ### :activitypub * `unfollow_blocked`: Whether blocks result in people getting unfollowed * `outgoing_blocks`: Whether to federate blocks to other instances -- cgit v1.2.3 From 7f97fbc1ae8d38c88d32739e968b4f2572c755a8 Mon Sep 17 00:00:00 2001 From: Mark Felder Date: Mon, 18 Mar 2024 15:36:26 -0400 Subject: Update minimum Postgres version to 11.0; disable JIT This release is where JIT was introduced and it should be disabled. Pleroma's queries do not benefit from JIT, but it can increase latency of queries. --- docs/installation/debian_based_jp.md | 4 ++-- docs/installation/generic_dependencies.include | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/installation/debian_based_jp.md b/docs/installation/debian_based_jp.md index 1424ad7f4..b6b5c9c07 100644 --- a/docs/installation/debian_based_jp.md +++ b/docs/installation/debian_based_jp.md @@ -12,8 +12,8 @@ Note: This article is potentially outdated because at this time we may not have ### 必要なソフトウェア -- PostgreSQL 9.6以上 (Ubuntu16.04では9.5しか提供されていないので，[](https://www.postgresql.org/download/linux/ubuntu/)こちらから新しいバージョンを入手してください) -- `postgresql-contrib` 9.6以上 (同上) +- PostgreSQL 11.0以上 (Ubuntu16.04では9.5しか提供されていないので，[](https://www.postgresql.org/download/linux/ubuntu/)こちらから新しいバージョンを入手してください) +- `postgresql-contrib` 11.0以上 (同上) - Elixir 1.8 以上 ([Debianのリポジトリからインストールしないこと！！！ ここからインストールすること！](https://elixir-lang.org/install.html#unix-and-unix-like)。または [asdf](https://github.com/asdf-vm/asdf) をpleromaユーザーでインストールしてください) - `erlang-dev` - `erlang-nox` diff --git a/docs/installation/generic_dependencies.include b/docs/installation/generic_dependencies.include index aebf21e7c..6572716ed 100644 --- a/docs/installation/generic_dependencies.include +++ b/docs/installation/generic_dependencies.include @@ -1,6 +1,6 @@ ## Required dependencies -* PostgreSQL >=9.6 +* PostgreSQL >=11.0 * Elixir >=1.11.0 <1.15 * Erlang OTP >=22.2.0 (supported: <27) * git -- cgit v1.2.3 From ccc3ac241f5b7c88b36efe60a4f9e5d791d2d49a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?marcin=20miko=C5=82ajczak?= Date: Sat, 6 Apr 2024 10:54:59 +0200 Subject: Add hint to rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: marcin mikołajczak --- docs/development/API/admin_api.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/development/API/admin_api.md b/docs/development/API/admin_api.md index 7bbed16d6..5b373b8e1 100644 --- a/docs/development/API/admin_api.md +++ b/docs/development/API/admin_api.md @@ -1764,7 +1764,8 @@ Note that this differs from the Mastodon API variant: Mastodon API only returns { "id": "1", "priority": 1, - "text": "There are no rules" + "text": "There are no rules", + "hint": null } ] ``` @@ -1775,6 +1776,7 @@ Note that this differs from the Mastodon API variant: Mastodon API only returns - Params: - `text`: string, required, rule content + - `hint`: string, optional, rule description - `priority`: integer, optional, rule ordering priority - Response: JSON, a single rule @@ -1785,6 +1787,7 @@ Note that this differs from the Mastodon API variant: Mastodon API only returns - Params: - `text`: string, optional, rule content + - `hint`: string, optional, rule description - `priority`: integer, optional, rule ordering priority - Response: JSON, a single rule -- cgit v1.2.3 From c50f0f31f418037063bd97efcdc0f60b89594212 Mon Sep 17 00:00:00 2001 From: Lain Soykaf Date: Tue, 14 May 2024 16:56:58 +0400 Subject: Docs/Search: Add basic documentation of the qdrant search --- docs/configuration/search.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/configuration/search.md b/docs/configuration/search.md index 0316c9bf4..682d1e52a 100644 --- a/docs/configuration/search.md +++ b/docs/configuration/search.md @@ -10,6 +10,12 @@ To use built-in search that has no external dependencies, set the search module While it has no external dependencies, it has problems with performance and relevancy. +## QdrantSearch + +This uses the vector search engine [Qdrant](https://qdrant.tech) to search the posts in a vector space. This needs a way to generate embeddings, for now only the [Ollama](Ollama) api is supported. + +The default settings will support a setup where both Ollama and Qdrant run on the same system as pleroma. The embedding model used by Ollama will need to be pulled first (e.g. `ollama pull snowflake-arctic-embed:xs`) for the embedding to work. + ## Meilisearch Note that it's quite a bit more memory hungry than PostgreSQL (around 4-5G for ~1.2 million -- cgit v1.2.3 From e142ea400a9ed3595f8d432edd90ea26fc7d2eb5 Mon Sep 17 00:00:00 2001 From: Lain Soykaf Date: Sun, 19 May 2024 12:42:08 +0400 Subject: Docs: Switch docs from Ollama to OpenAI. --- docs/configuration/search.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/configuration/search.md b/docs/configuration/search.md index 682d1e52a..388f5acd1 100644 --- a/docs/configuration/search.md +++ b/docs/configuration/search.md @@ -12,9 +12,9 @@ While it has no external dependencies, it has problems with performance and rele ## QdrantSearch -This uses the vector search engine [Qdrant](https://qdrant.tech) to search the posts in a vector space. This needs a way to generate embeddings, for now only the [Ollama](Ollama) api is supported. +This uses the vector search engine [Qdrant](https://qdrant.tech) to search the posts in a vector space. This needs a way to generate embeddings and uses the [OpenAI API](https://platform.openai.com/docs/guides/embeddings/what-are-embeddings). This is implemented by several project besides OpenAI itself, including the python-based fastembed-server found in `supplemental/search/fastembed-api`. -The default settings will support a setup where both Ollama and Qdrant run on the same system as pleroma. The embedding model used by Ollama will need to be pulled first (e.g. `ollama pull snowflake-arctic-embed:xs`) for the embedding to work. +The default settings will support a setup where both the fastembed server and Qdrant run on the same system as pleroma. ## Meilisearch -- cgit v1.2.3 From 6a3a0cc0f5995185428c92f3c53e9c8524ea6856 Mon Sep 17 00:00:00 2001 From: Lain Soykaf Date: Sun, 19 May 2024 13:20:37 +0400 Subject: Docs: Write docs for the QdrantSearch --- docs/configuration/search.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/configuration/search.md b/docs/configuration/search.md index 388f5acd1..6598e533f 100644 --- a/docs/configuration/search.md +++ b/docs/configuration/search.md @@ -14,7 +14,25 @@ While it has no external dependencies, it has problems with performance and rele This uses the vector search engine [Qdrant](https://qdrant.tech) to search the posts in a vector space. This needs a way to generate embeddings and uses the [OpenAI API](https://platform.openai.com/docs/guides/embeddings/what-are-embeddings). This is implemented by several project besides OpenAI itself, including the python-based fastembed-server found in `supplemental/search/fastembed-api`. -The default settings will support a setup where both the fastembed server and Qdrant run on the same system as pleroma. +The default settings will support a setup where both the fastembed server and Qdrant run on the same system as pleroma. To use it, set the search provider and run the fastembed server, see the README in `supplemental/search/fastembed-api`: + +https://qdrant.github.io/fastembed/examples/Supported_Models/ + +> config :pleroma, Pleroma.Search, module: Pleroma.Search.QdrantSearch + +You will also need to create the Qdrant index once by running `mix pleroma.search.indexer create_index`. Running `mix pleroma.search.indexer index` will retroactively index the last 100_000 activities. + +### Indexing and model options + +To see the available configuration options, check out the QdrantSearch section in `config/config.exs`. + +The default indexing option work for the default model (`snowflake-arctic-embed-xs`). To optimize for a low memory footprint, adjust the index configuration as described in the [Qdrant docs](https://qdrant.tech/documentation/guides/optimize/). + +Different embedding models will need different vector size settings. You can see a list of the models supported by the fastembed server [here](https://qdrant.github.io/fastembed/examples/Supported_Models), including their vector dimensions. These vector dimensions need to be set in the `qdrant_index_configuration`. + +E.g, If you want to use `sentence-transformers/all-MiniLM-L6-v2` as a model, you will not need to adjust things, because it and `snowflake-arctic-embed-xs` are both 384 dimensional models. If you want to use `snowflake/snowflake-arctic-embed-l`, you will need to adjust the `size` parameter in the `qdrant_index_configuration` to 1024, as it has a dimension of 1024. + +When using a different model, you will need do drop the index and recreate it (`mix pleroma.search.indexer drop_index` and `mix pleroma.search.indexer create_index`), as the different embeddings are not compatible with each other. ## Meilisearch -- cgit v1.2.3 From 6ec306d0684f3c5c05d768a3c431008925f21f15 Mon Sep 17 00:00:00 2001 From: Lain Soykaf Date: Sun, 19 May 2024 13:24:24 +0400 Subject: Docs: Add more information about index memory consumption. --- docs/configuration/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/configuration/search.md b/docs/configuration/search.md index 6598e533f..ed85acd2a 100644 --- a/docs/configuration/search.md +++ b/docs/configuration/search.md @@ -26,7 +26,7 @@ You will also need to create the Qdrant index once by running `mix pleroma.searc To see the available configuration options, check out the QdrantSearch section in `config/config.exs`. -The default indexing option work for the default model (`snowflake-arctic-embed-xs`). To optimize for a low memory footprint, adjust the index configuration as described in the [Qdrant docs](https://qdrant.tech/documentation/guides/optimize/). +The default indexing option work for the default model (`snowflake-arctic-embed-xs`). To optimize for a low memory footprint, adjust the index configuration as described in the [Qdrant docs](https://qdrant.tech/documentation/guides/optimize/). See also [this blog post](https://qdrant.tech/articles/memory-consumption/) that goes into detail. Different embedding models will need different vector size settings. You can see a list of the models supported by the fastembed server [here](https://qdrant.github.io/fastembed/examples/Supported_Models), including their vector dimensions. These vector dimensions need to be set in the `qdrant_index_configuration`. -- cgit v1.2.3 From dbaab6f54e306e5fb930ce1ed0699631c8aeaae1 Mon Sep 17 00:00:00 2001 From: Lain Soykaf Date: Sun, 19 May 2024 13:38:31 +0400 Subject: Docs: Mention running the Qdrant server --- docs/configuration/search.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/configuration/search.md b/docs/configuration/search.md index ed85acd2a..d34f84d4f 100644 --- a/docs/configuration/search.md +++ b/docs/configuration/search.md @@ -16,10 +16,10 @@ This uses the vector search engine [Qdrant](https://qdrant.tech) to search the p The default settings will support a setup where both the fastembed server and Qdrant run on the same system as pleroma. To use it, set the search provider and run the fastembed server, see the README in `supplemental/search/fastembed-api`: -https://qdrant.github.io/fastembed/examples/Supported_Models/ - > config :pleroma, Pleroma.Search, module: Pleroma.Search.QdrantSearch +Then, start the Qdrant server, see [here](https://qdrant.tech/documentation/quick-start/) for instructions. + You will also need to create the Qdrant index once by running `mix pleroma.search.indexer create_index`. Running `mix pleroma.search.indexer index` will retroactively index the last 100_000 activities. ### Indexing and model options -- cgit v1.2.3 From 618b77071afb480b763a493bfcd9b376effedaaf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?marcin=20miko=C5=82ajczak?= Date: Sat, 25 May 2024 09:10:11 +0200 Subject: Update pleroma_api.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: marcin mikołajczak --- docs/development/API/pleroma_api.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/development/API/pleroma_api.md b/docs/development/API/pleroma_api.md index 267dfc1ec..57d333ffe 100644 --- a/docs/development/API/pleroma_api.md +++ b/docs/development/API/pleroma_api.md @@ -295,9 +295,7 @@ See [Admin-API](admin_api.md) "id": "9umDrYheeY451cQnEe", "name": "Read later", "emoji": "🕓", - "source": { - "emoji": "🕓" - } + "emoji_url": null } ] ``` -- cgit v1.2.3 From f4693dc6710c8c8ac878c2845793c7d138f90c04 Mon Sep 17 00:00:00 2001 From: Mark Felder Date: Wed, 27 Dec 2023 22:32:42 -0500 Subject: Update Prometheus/Grafana docs for PromEx --- docs/development/API/prometheus.md | 65 ++++++++++++++++++++------------------ 1 file changed, 34 insertions(+), 31 deletions(-) (limited to 'docs') diff --git a/docs/development/API/prometheus.md b/docs/development/API/prometheus.md index a5158d905..140291fe0 100644 --- a/docs/development/API/prometheus.md +++ b/docs/development/API/prometheus.md @@ -1,44 +1,47 @@ -# Prometheus Metrics +# Prometheus / OpenTelemetry Metrics -Pleroma includes support for exporting metrics via the [prometheus_ex](https://github.com/deadtrickster/prometheus.ex) library. +Pleroma includes support for exporting metrics via the [prom_ex](https://github.com/akoutmos/prom_ex) library. +The metrics are exposed by a dedicated webserver/port to improve privacy and security. Config example: ``` -config :prometheus, Pleroma.Web.Endpoint.MetricsExporter, - enabled: true, - auth: {:basic, "myusername", "mypassword"}, - ip_whitelist: ["127.0.0.1"], - path: "/api/pleroma/app_metrics", - format: :text -``` - -* `enabled` (Pleroma extension) enables the endpoint -* `ip_whitelist` (Pleroma extension) could be used to restrict access only to specified IPs -* `auth` sets the authentication (`false` for no auth; configurable to HTTP Basic Auth, see [prometheus-plugs](https://github.com/deadtrickster/prometheus-plugs#exporting) documentation) -* `format` sets the output format (`:text` or `:protobuf`) -* `path` sets the path to app metrics page - - -## `/api/pleroma/app_metrics` +config :pleroma, Pleroma.PromEx, + disabled: false, + manual_metrics_start_delay: :no_delay, + drop_metrics_groups: [], + grafana: [ + host: System.get_env("GRAFANA_HOST", "http://localhost:3000"), + auth_token: System.get_env("GRAFANA_TOKEN"), + upload_dashboards_on_start: false, + folder_name: "BEAM", + annotate_app_lifecycle: true + ], + metrics_server: [ + port: 4021, + path: "/metrics", + protocol: :http, + pool_size: 5, + cowboy_opts: [], + auth_strategy: :none + ], + datasource: "Prometheus" -### Exports Prometheus application metrics - -* Method: `GET` -* Authentication: not required by default (see configuration options above) -* Params: none -* Response: text +``` -## Grafana +PromEx supports the ability to automatically publish dashboards to your Grafana server as well as register Annotations. If you do not wish to configure this capability you must generate the dashboard JSON files and import them directly. You can find the mix commands in the upstream [documentation](https://hexdocs.pm/prom_ex/Mix.Tasks.PromEx.Dashboard.Export.html). You can find the list of modules enabled in Pleroma for which you should generate dashboards for by examining the contents of the `lib/pleroma/prom_ex.ex` module. -### Config example +## prometheus.yml -The following is a config example to use with [Grafana](https://grafana.com) +The following is a bare minimum config example to use with [Prometheus](https://prometheus.io) or Prometheus-compatible software like [VictoriaMetrics](https://victoriametrics.com). ``` - - job_name: 'beam' - metrics_path: /api/pleroma/app_metrics - scheme: https +global: + scrape_interval: 15s + +scrape_configs: + - job_name: 'pleroma' + scheme: http static_configs: - - targets: ['pleroma.soykaf.com'] + - targets: ['pleroma.soykaf.com:4021'] ``` -- cgit v1.2.3 From fc7ce339edc40cb791d321a20f01f2568337b845 Mon Sep 17 00:00:00 2001 From: Lain Soykaf Date: Mon, 27 May 2024 21:28:20 +0400 Subject: Cheatsheet: Add allow_unsafe_eval --- docs/configuration/cheatsheet.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index ca2ce6369..78997c4db 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -472,6 +472,7 @@ This will make Pleroma listen on `127.0.0.1` port `8080` and generate urls start * ``ct_max_age``: The maximum age for the `Expect-CT` header if sent. * ``referrer_policy``: The referrer policy to use, either `"same-origin"` or `"no-referrer"`. * ``report_uri``: Adds the specified url to `report-uri` and `report-to` group in CSP header. +* `allow_unsafe_eval`: Adds `wasm-unsafe-eval` to the CSP header. Needed for some non-essential frontend features like Flash emulation. ### Pleroma.Web.Plugs.RemoteIp -- cgit v1.2.3