From 3ad7492f9dd1c76cdbc64ad2246f8e9c8c5c4ae6 Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Fri, 4 Sep 2020 18:30:39 +0400 Subject: Add config for Pleroma.Backup --- 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 42e5fe808..cc4081f14 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -1083,6 +1083,11 @@ Control favicons for instances. * `enabled`: Allow/disallow displaying and getting instances favicons +## Account Backup + +* `:purge_after_days` an integer, remove backup achives after N days. +* `:limit_days` an integer, limit user to export not more often than once per N days. + ## Frontend management Frontends in Pleroma are swappable - you can specify which one to use here. -- cgit v1.2.3 From 386199063b9be9fc30ad403f6afb03bf6ca47298 Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Thu, 10 Sep 2020 21:09:20 +0400 Subject: Document `/api/pleroma/backups` API endpoint --- docs/API/pleroma_api.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) (limited to 'docs') diff --git a/docs/API/pleroma_api.md b/docs/API/pleroma_api.md index 3fd141bd2..aeb266159 100644 --- a/docs/API/pleroma_api.md +++ b/docs/API/pleroma_api.md @@ -615,3 +615,41 @@ Emoji reactions work a lot like favourites do. They make it possible to react to {"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]} ] ``` + +## `POST /api/pleroma/backups` +### Create a user backup archive + +* Method: `POST` +* Authentication: not required +* Params: none +* Response: JSON +* Example response: + +```json +[{ + "content_type": "application/zip", + "file_size": 0, + "inserted_at": "2020-09-10T16:18:03.000Z", + "processed": false, + "url": "https://example.com/media/backups/archive-foobar-20200910T161803-QUhx6VYDRQ2wfV0SdA2Pfj_2CLM_ATUlw-D5l5TJf4Q.zip" +}] +``` + +## `GET /api/pleroma/backups` +### Lists user backups + +* Method: `GET` +* Authentication: not required +* Params: none +* Response: JSON +* Example response: + +```json +[{ + "content_type": "application/zip", + "file_size": 55457, + "inserted_at": "2020-09-10T16:18:03.000Z", + "processed": true, + "url": "https://example.com/media/backups/archive-foobar-20200910T161803-QUhx6VYDRQ2wfV0SdA2Pfj_2CLM_ATUlw-D5l5TJf4Q.zip" +}] +``` -- cgit v1.2.3 From 27bc121ec00a7b088030d6fb36c7e731f5b072b6 Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Tue, 15 Sep 2020 18:07:28 +0400 Subject: Require email --- docs/configuration/cheatsheet.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs') diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index cc4081f14..8da8a7bd6 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -1085,6 +1085,9 @@ Control favicons for instances. ## Account Backup +!!! note + Requires enabled email + * `:purge_after_days` an integer, remove backup achives after N days. * `:limit_days` an integer, limit user to export not more often than once per N days. -- cgit v1.2.3 From e52dd62e14a956a28a706124464f3ac4b985080d Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Wed, 16 Sep 2020 23:21:13 +0400 Subject: Add configurable temporary directory --- 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 8da8a7bd6..9271964f1 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -1090,6 +1090,12 @@ Control favicons for instances. * `:purge_after_days` an integer, remove backup achives 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 + 2. the directory named by the TEMP environment variable + 3. the directory named by the TMP environment variable + 4. C:\TMP on Windows or /tmp on Unix-like operating systems + 5. as a last resort, the current working directory ## Frontend management -- cgit v1.2.3 From 17562bf4147ab03e171b1f1d365a512f2e5b3202 Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Sun, 20 Sep 2020 20:43:27 +0400 Subject: Move API endpoints to `/api/v1/pleroma/backups` --- docs/API/pleroma_api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/API/pleroma_api.md b/docs/API/pleroma_api.md index aeb266159..fa3a9a449 100644 --- a/docs/API/pleroma_api.md +++ b/docs/API/pleroma_api.md @@ -616,7 +616,7 @@ Emoji reactions work a lot like favourites do. They make it possible to react to ] ``` -## `POST /api/pleroma/backups` +## `POST /api/v1/pleroma/backups` ### Create a user backup archive * Method: `POST` @@ -635,7 +635,7 @@ Emoji reactions work a lot like favourites do. They make it possible to react to }] ``` -## `GET /api/pleroma/backups` +## `GET /api/v1/pleroma/backups` ### Lists user backups * Method: `GET` -- cgit v1.2.3 From 6d5f02a1da81ed7693c5ae364a25bc0b54ee1a38 Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Sat, 26 Sep 2020 20:34:44 +0400 Subject: Fix API documentation --- docs/API/pleroma_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/API/pleroma_api.md b/docs/API/pleroma_api.md index fa3a9a449..7a0a80dad 100644 --- a/docs/API/pleroma_api.md +++ b/docs/API/pleroma_api.md @@ -620,7 +620,7 @@ Emoji reactions work a lot like favourites do. They make it possible to react to ### Create a user backup archive * Method: `POST` -* Authentication: not required +* Authentication: required * Params: none * Response: JSON * Example response: -- cgit v1.2.3 From 9c672ecbb5d4477cd16d2139a2cb66d3923ac5c8 Mon Sep 17 00:00:00 2001 From: Alex Gleason Date: Thu, 8 Oct 2020 20:01:48 -0500 Subject: Remote Timeline: add Streaming support --- docs/API/differences_in_mastoapi_responses.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/API/differences_in_mastoapi_responses.md b/docs/API/differences_in_mastoapi_responses.md index 38865dc68..bb1000b0b 100644 --- a/docs/API/differences_in_mastoapi_responses.md +++ b/docs/API/differences_in_mastoapi_responses.md @@ -9,9 +9,13 @@ Pleroma uses 128-bit ids as opposed to Mastodon's 64 bits. However just like Mas ## Timelines Adding the parameter `with_muted=true` to the timeline queries will also return activities by muted (not by blocked!) users. + Adding the parameter `exclude_visibilities` to the timeline queries will exclude the statuses with the given visibilities. The parameter accepts an array of visibility types (`public`, `unlisted`, `private`, `direct`), e.g., `exclude_visibilities[]=direct&exclude_visibilities[]=private`. + Adding the parameter `reply_visibility` to the public and home timelines queries will filter replies. Possible values: without parameter (default) shows all replies, `following` - replies directed to you or users you follow, `self` - replies directed to you. +Adding the parameter `instance=lain.com` to the public timeline will show only statuses originating from `lain.com` (or any remote instance). + ## Statuses - `visibility`: has an additional possible value `list` @@ -249,6 +253,8 @@ Has these additional fields under the `pleroma` object: There is an additional `user:pleroma_chat` stream. Incoming chat messages will make the current chat be sent to this `user` stream. The `event` of an incoming chat message is `pleroma:chat_update`. The payload is the updated chat with the incoming chat message in the `last_message` field. +For viewing remote server timelines, there are `public:remote` and `public:remote:media` streams. Each of these accept a parameter like `?instance=lain.com`. + ## Not implemented Pleroma is generally compatible with the Mastodon 2.7.2 API, but some newer features and non-essential features are omitted. These features usually return an HTTP 200 status code, but with an empty response. While they may be added in the future, they are considered low priority. -- cgit v1.2.3 From 1b8fd7e65af980c42b72f584c2a957b12ca5c78b Mon Sep 17 00:00:00 2001 From: Mark Felder Date: Fri, 16 Oct 2020 17:32:05 +0000 Subject: Adds feature to permit e.g., local admins and community moderators to automatically follow all newly registered accounts --- 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 0b13d7e88..f4b4b6c3c 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -45,6 +45,7 @@ To add configuration to your config file, you can copy it from the base config. older software for theses nicknames. * `max_pinned_statuses`: The maximum number of pinned statuses. `0` will disable the feature. * `autofollowed_nicknames`: Set to nicknames of (local) users that every new user should automatically follow. +* `autofollowing_nicknames`: Set to nicknames of (local) users that automatically follows every newly registered user. * `attachment_links`: Set to true to enable automatically adding attachment link text to statuses. * `max_report_comment_size`: The maximum size of the report comment (Default: `1000`). * `safe_dm_mentions`: If set to true, only mentions at the beginning of a post will be used to address people in direct messages. This is to prevent accidental mentioning of people when talking about them (e.g. "@friend hey i really don't like @enemy"). Default: `false`. -- cgit v1.2.3 From 524fb0e4c2561f4a2e4c8e58519df991f034c901 Mon Sep 17 00:00:00 2001 From: Ivan Tashkinov Date: Sun, 18 Oct 2020 21:22:21 +0300 Subject: [#1668] Restricted access to app metrics endpoint by default. Added ability to configure IP whitelist for this endpoint. Added tests and documentation. --- docs/API/prometheus.md | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/API/prometheus.md b/docs/API/prometheus.md index 19c564e3c..a5158d905 100644 --- a/docs/API/prometheus.md +++ b/docs/API/prometheus.md @@ -2,15 +2,37 @@ Pleroma includes support for exporting metrics via the [prometheus_ex](https://github.com/deadtrickster/prometheus.ex) library. +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` + ### Exports Prometheus application metrics + * Method: `GET` -* Authentication: not required +* Authentication: not required by default (see configuration options above) * Params: none -* Response: JSON +* Response: text ## Grafana + ### Config example + The following is a config example to use with [Grafana](https://grafana.com) ``` -- cgit v1.2.3 From ad605e3e16ba3f6ee3df7a0a3e6705036fef369f Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Tue, 20 Oct 2020 17:16:58 +0400 Subject: Rename `Pleroma.Backup` to `Pleroma.User.Backup` --- 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 aafc43f3d..b40a2aebf 100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -1077,7 +1077,7 @@ Control favicons for instances. * `enabled`: Allow/disallow displaying and getting instances favicons -## Account Backup +## Pleroma.User.Backup !!! note Requires enabled email -- cgit v1.2.3 From b18b93bbed925e5058d941662e93f0a46a27c325 Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Wed, 21 Oct 2020 21:42:21 +0400 Subject: Fix formatting and typos in "Managing frontends" guide --- docs/administration/CLI_tasks/frontend.md | 93 ++++++++++++++++++++----------- 1 file changed, 60 insertions(+), 33 deletions(-) (limited to 'docs') diff --git a/docs/administration/CLI_tasks/frontend.md b/docs/administration/CLI_tasks/frontend.md index 7d1c1e937..d4a48cb56 100644 --- a/docs/administration/CLI_tasks/frontend.md +++ b/docs/administration/CLI_tasks/frontend.md @@ -1,12 +1,23 @@ # Managing frontends -`mix pleroma.frontend install [--ref ] [--file ] [--build-url ] [--path ] [--build-dir ]` +=== "OTP" + + ```sh + ./bin/pleroma_ctl frontend install [--ref ] [--file ] [--build-url ] [--path ] [--build-dir ] + ``` + +=== "From Source" + + ```sh + mix pleroma.frontend install [--ref ] [--file ] [--build-url ] [--path ] [--build-dir ] + ``` Frontend can be installed either from local zip file, or automatically downloaded from the web. -You can give all the options directly on the command like, but missing information will be filled out by looking at the data configured under `frontends.available` in the config files. +You can give all the options directly on the command line, but missing information will be filled out by looking at the data configured under `frontends.available` in the config files. + +Currently, known `` values are: -Currently known `` values are: - [admin-fe](https://git.pleroma.social/pleroma/admin-fe) - [kenoma](http://git.pleroma.social/lambadalambda/kenoma) - [pleroma-fe](http://git.pleroma.social/pleroma/pleroma-fe) @@ -19,51 +30,67 @@ You can still install frontends that are not configured, see below. For a frontend configured under the `available` key, it's enough to install it by name. -```sh tab="OTP" -./bin/pleroma_ctl frontend install pleroma -``` +=== "OTP" + + ```sh + ./bin/pleroma_ctl frontend install pleroma + ``` + +=== "From Source" -```sh tab="From Source" -mix pleroma.frontend install pleroma -``` + ```sh + mix pleroma.frontend install pleroma + ``` -This will download the latest build for the the pre-configured `ref` and install it. It can then be configured as the one of the served frontends in the config file (see `primary` or `admin`). +This will download the latest build for the pre-configured `ref` and install it. It can then be configured as the one of the served frontends in the config file (see `primary` or `admin`). -You can override any of the details. To install a pleroma build from a different url, you could do this: +You can override any of the details. To install a pleroma build from a different URL, you could do this: -```sh tab="OPT" -./bin/pleroma_ctl frontend install pleroma --ref 2hu_edition --build-url https://example.org/raymoo.zip -``` +=== "OTP" -```sh tab="From Source" -mix pleroma.frontend install pleroma --ref 2hu_edition --build-url https://example.org/raymoo.zip -``` + ```sh + ./bin/pleroma_ctl frontend install pleroma --ref 2hu_edition --build-url https://example.org/raymoo.zip + ``` + +=== "From Source" + + ```sh + mix pleroma.frontend install pleroma --ref 2hu_edition --build-url https://example.org/raymoo.zip + ``` Similarly, you can also install from a local zip file. -```sh tab="OTP" -./bin/pleroma_ctl frontend install pleroma --ref mybuild --file ~/Downloads/doomfe.zip -``` +=== "OTP" + + ```sh + ./bin/pleroma_ctl frontend install pleroma --ref mybuild --file ~/Downloads/doomfe.zip + ``` -```sh tab="From Source" -mix pleroma.frontend install pleroma --ref mybuild --file ~/Downloads/doomfe.zip -``` +=== "From Source" -The resulting frontend will always be installed into a folder of this template: `${instance_static}/frontends/${name}/${ref}` + ```sh + mix pleroma.frontend install pleroma --ref mybuild --file ~/Downloads/doomfe.zip + ``` -Careful: This folder will be completely replaced on installation +The resulting frontend will always be installed into a folder of this template: `${instance_static}/frontends/${name}/${ref}`. + +Careful: This folder will be completely replaced on installation. ## Example installation for an unknown frontend -The installation process is the same, but you will have to give all the needed options on the commond line. For example: +The installation process is the same, but you will have to give all the needed options on the command line. For example: + +=== "OTP" + + ```sh + ./bin/pleroma_ctl frontend install gensokyo --ref master --build-url https://gensokyo.2hu/builds/marisa.zip + ``` -```sh tab="OTP" -./bin/pleroma_ctl frontend install gensokyo --ref master --build-url https://gensokyo.2hu/builds/marisa.zip -``` +=== "From Source" -```sh tab="From Source" -mix pleroma.frontend install gensokyo --ref master --build-url https://gensokyo.2hu/builds/marisa.zip -``` + ```sh + mix pleroma.frontend install gensokyo --ref master --build-url https://gensokyo.2hu/builds/marisa.zip + ``` -If you don't have a zip file but just want to install a frontend from a local path, you can simply copy the files over a folder of this template: `${instance_static}/frontends/${name}/${ref}` +If you don't have a zip file but just want to install a frontend from a local path, you can simply copy the files over a folder of this template: `${instance_static}/frontends/${name}/${ref}`. -- cgit v1.2.3 From 51189ad365a462163a4c98a7b5cb7ae74f2d634a Mon Sep 17 00:00:00 2001 From: Maksim Pechnikov Date: Fri, 25 Sep 2020 16:40:50 +0300 Subject: update docs --- docs/API/admin_api.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/API/admin_api.md b/docs/API/admin_api.md index 7bf13daef..f7b5bcae7 100644 --- a/docs/API/admin_api.md +++ b/docs/API/admin_api.md @@ -20,12 +20,14 @@ Configuration options: - `external`: only external users - `active`: only active users - `need_approval`: only unapproved users + - `unconfirmed`: only unconfirmed users - `deactivated`: only deactivated users - `is_admin`: users with admin role - `is_moderator`: users with moderator role - *optional* `page`: **integer** page number - *optional* `page_size`: **integer** number of users per page (default is `50`) - *optional* `tags`: **[string]** tags list + - *optional* `actor_types`: **[string]** actor type list (`Person`, `Service`, `Application`) - *optional* `name`: **string** user display name - *optional* `email`: **string** user email - Example: `https://mypleroma.org/api/pleroma/admin/users?query=john&filters=local,active&page=1&page_size=10&tags[]=some_tag&tags[]=another_tag&name=display_name&email=email@example.com` -- cgit v1.2.3 From 8e41baff40555ef7c74c8842d6fbfebc2368631a Mon Sep 17 00:00:00 2001 From: eugenijm Date: Sat, 31 Oct 2020 05:50:48 +0300 Subject: Add idempotency_key to the chat_message entity. --- docs/API/chats.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/API/chats.md b/docs/API/chats.md index aa6119670..9857aac67 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -173,11 +173,14 @@ Returned data: "created_at": "2020-04-21T15:06:45.000Z", "emojis": [], "id": "12", - "unread": false + "unread": false, + "idempotency_key": "75442486-0874-440c-9db1-a7006c25a31f" } ] ``` +- idempotency_key: The copy of the `idempotency-key` HTTP request header that can be used for optimistic message sending. Included only during the first few minutes after the message creation. + ### Posting a chat message Posting a chat message for given Chat id works like this: -- cgit v1.2.3 From ca95cbe0b48b6c64e6e33addf79e4d212d5f9872 Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Wed, 4 Nov 2020 16:40:12 +0400 Subject: Add `with_muted` param to ChatController.index/2 --- docs/API/chats.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/API/chats.md b/docs/API/chats.md index 9857aac67..f50144c86 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -116,6 +116,10 @@ The modified chat message This will return a list of chats that you have been involved in, sorted by their last update (so new chats will be at the top). +Parameters: + +- with_muted: Include chats from muted users (boolean). + Returned data: ```json -- cgit v1.2.3