From 7493d8f49da64ae83b08b70b8ad18af62e6a65de Mon Sep 17 00:00:00 2001 From: Oneric Date: Tue, 16 Jan 2024 22:12:52 +0100 Subject: [PATCH 1/4] Document live dashboard --- docs/docs/administration/monitoring.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/docs/administration/monitoring.md b/docs/docs/administration/monitoring.md index 9233fbe34..b7a748731 100644 --- a/docs/docs/administration/monitoring.md +++ b/docs/docs/administration/monitoring.md @@ -3,7 +3,7 @@ If you run akkoma, you may be inclined to collect metrics to ensure your instance is running smoothly, and that there's nothing quietly failing in the background. -To facilitate this, akkoma exposes prometheus metrics to be scraped. +To facilitate this, akkoma exposes a dashboard and prometheus metrics to be scraped. ## Prometheus @@ -31,3 +31,15 @@ Once you have your token of the form `Bearer $ACCESS_TOKEN`, you can use that in - targets: - example.com ``` + +## Dashboard + +Administrators can access a live dashboard under `/phoenix/live_dashboard` +giving an overview of uptime, software versions, database stats and more. + +The dashboard also includes a variation of the prometheus metrics, however +they do not exactly match due to respective limitations of the dashboard +and the prometheus exporter. +Even more important, the dashboard collects metrics locally in the browser +only while the page is open and cannot give a view on their past history. +For proper monitoring it is recommended to set up prometheus. From 6bb455702d90ea27fdc8802bedea299654a7be07 Mon Sep 17 00:00:00 2001 From: Oneric Date: Sun, 28 Jan 2024 19:49:20 +0100 Subject: [PATCH 2/4] Document Akkoma API --- CHANGELOG.md | 1 + docs/docs/development/API/akkoma_api.md | 140 ++++++++++++++++++++++++ 2 files changed, 141 insertions(+) create mode 100644 docs/docs/development/API/akkoma_api.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 8a38e80ba..504d70765 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## Added - Full compatibility with Erlang OTP26 - handling of GET /api/v1/preferences +- Akkoma API is now documented ## Changed - OTP builds are now built on erlang OTP26 diff --git a/docs/docs/development/API/akkoma_api.md b/docs/docs/development/API/akkoma_api.md new file mode 100644 index 000000000..786445459 --- /dev/null +++ b/docs/docs/development/API/akkoma_api.md @@ -0,0 +1,140 @@ +# Akkoma API + +Request authentication (if required) and parameters work the same as for [Pleroma API](pleroma_api.md). + +## `/api/v1/akkoma/preferred_frontend/available` +### Returns the available frontends which can be picked as the preferred choice +* Method: `GET` +* Authentication: not required +* Params: none +* Response: JSON +* Example response: +```json +["pleroma-fe/stable"] +``` + +!!! note + There’s also a browser UI under `/akkoma/frontend` + for interactively querying and changing this. + +## `/api/v1/akkoma/preferred_frontend` +### Configures the preferred frontend of this session +* Method: `PUT` +* Authentication: not required +* Params: + * `frontend_name`: STRING containing one of the available frontends +* Response: JSON +* Example response: +```json +{"frontend_name":"pleroma-fe/stable"} +``` + +!!! note + There’s also a browser UI under `/akkoma/frontend` + for interactively querying and changing this. + +## `/api/v1/akkoma/metrics` +### Provides metrics for Prometheus to scrape +* Method: `GET` +* Authentication: required (admin:metrics) +* Params: none +* Response: text +* Example response: +``` +# HELP pleroma_remote_users_total +# TYPE pleroma_remote_users_total gauge +pleroma_remote_users_total 25 +# HELP pleroma_local_statuses_total +# TYPE pleroma_local_statuses_total gauge +pleroma_local_statuses_total 17 +# HELP pleroma_domains_total +# TYPE pleroma_domains_total gauge +pleroma_domains_total 4 +# HELP pleroma_local_users_total +# TYPE pleroma_local_users_total gauge +pleroma_local_users_total 3 +... +``` + +## `/api/v1/akkoma/translation/languages` +### Returns available source and target languages for automated text translation +* Method: `GET` +* Authentication: required +* Params: none +* Response: JSON +* Example response: +```json +{ + "source": [ + {"code":"LV", "name":"Latvian"}, + {"code":"ZH", "name":"Chinese (traditional)"}, + {"code":"EN-US", "name":"English (American)"} + ], + "target": [ + {"code":"EN-GB", "name":"English (British)"}, + {"code":"JP", "name":"Japanese"} + ] +} +``` + +## `/api/v1/akkoma/frontend_settings/:frontend_name` +### Lists all configuration profiles of the selected frontend for the current user +* Method: `GET` +* Authentication: required +* Params: none +* Response: JSON +* Example response: +```json +[ + {"name":"default","version":31} +] +``` + +## `/api/v1/akkoma/frontend_settings/:frontend_name/:profile_name` +### Returns the full selected frontend settings profile of the current user +* Method: `GET` +* Authentication: required +* Params: none +* Response: JSON +* Example response: +```json +{ + "version": 31, + "settings": { + "streaming": true, + "conversationDisplay": "tree", + ... + } +} +``` + +## `/api/v1/akkoma/frontend_settings/:frontend_name/:profile_name` +### Updates the frontend settings profile +* Method: `PUT` +* Authentication: required +* Params: + * `version`: INTEGER + * `settings`: JSON object containing the entire new settings +* Response: JSON +* Example response: +```json +{ + "streaming": false, + "conversationDisplay": "tree", + ... +} +``` + +!!! note + The `version` field must be increased by exactly one on each update + +## `/api/v1/akkoma/frontend_settings/:frontend_name/:profile_name` +### Drops the specified frontend settings profile +* Method: `DELETE` +* Authentication: required +* Params: none +* Response: JSON +* Example response: +```json +{"deleted":"ok"} +``` From 711043f57dc4fba13cfc02a3cc9fe93a7f28a05f Mon Sep 17 00:00:00 2001 From: Oneric Date: Thu, 15 Feb 2024 16:01:43 +0100 Subject: [PATCH 3/4] Document bubble timeline API It was added in cb6e7359af353bb19262ac94b92b41a62819523e. --- docs/docs/development/API/akkoma_api.md | 6 ++++++ .../API/differences_in_mastoapi_responses.md | 14 +++++++++++--- 2 files changed, 17 insertions(+), 3 deletions(-) diff --git a/docs/docs/development/API/akkoma_api.md b/docs/docs/development/API/akkoma_api.md index 786445459..cc3f7ddec 100644 --- a/docs/docs/development/API/akkoma_api.md +++ b/docs/docs/development/API/akkoma_api.md @@ -138,3 +138,9 @@ pleroma_local_users_total 3 ```json {"deleted":"ok"} ``` + + +## `/api/v1/timelines/bubble` +### Returns a timeline for the local and closely related instances +Works like all other Mastodon-API timeline queries with the documented +[Akkoma-specific additions and tweaks](./differences_in_mastoapi_responses.md#timelines). diff --git a/docs/docs/development/API/differences_in_mastoapi_responses.md b/docs/docs/development/API/differences_in_mastoapi_responses.md index 053dc9663..207ecd6e7 100644 --- a/docs/docs/development/API/differences_in_mastoapi_responses.md +++ b/docs/docs/development/API/differences_in_mastoapi_responses.md @@ -8,20 +8,28 @@ Akkoma uses 128-bit ids as opposed to Mastodon's 64 bits. However, just like Mas ## Timelines +In addition to Mastodon’s timelines, there is also a “bubble timeline” showing +posts from the local instance and a set of closely related instances as chosen +by the administrator. It is available under `/api/v1/timelines/bubble`. + 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 `reply_visibility` to the public, bubble or 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). -Home, public, hashtag & list timelines accept these parameters: +All but the direct timeline accept these parameters: - `only_media`: show only statuses with media attached -- `local`: show only local statuses - `remote`: show only remote statuses +Home, public, hashtag & list timelines further accept: + +- `local`: show only local statuses + + ## Statuses - `visibility`: has additional possible values `list` and `local` (for local-only statuses) From cda597a05cd58448df4c054d76b696f4530afd2b Mon Sep 17 00:00:00 2001 From: Oneric Date: Thu, 15 Feb 2024 16:02:13 +0100 Subject: [PATCH 4/4] doc: fix Akkoma identification name Akkoma stopped pretending to be Pleroma here when the mix project name was changed in c07fcdbf2b3c28ae4d1d11df4d872f230410f2b5. --- .../docs/development/API/differences_in_mastoapi_responses.md | 2 +- lib/pleroma/web/api_spec/operations/instance_operation.ex | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/development/API/differences_in_mastoapi_responses.md b/docs/docs/development/API/differences_in_mastoapi_responses.md index 207ecd6e7..8451558ff 100644 --- a/docs/docs/development/API/differences_in_mastoapi_responses.md +++ b/docs/docs/development/API/differences_in_mastoapi_responses.md @@ -1,6 +1,6 @@ # Differences in Mastodon API responses from vanilla Mastodon -A Akkoma instance can be identified by " (compatible; Pleroma )" present in `version` field in response from `/api/v1/instance` +A Akkoma instance can be identified by " (compatible; Akkoma )" present in `version` field in response from `/api/v1/instance` ## Flake IDs diff --git a/lib/pleroma/web/api_spec/operations/instance_operation.ex b/lib/pleroma/web/api_spec/operations/instance_operation.ex index 9384acc32..c72fee197 100644 --- a/lib/pleroma/web/api_spec/operations/instance_operation.ex +++ b/lib/pleroma/web/api_spec/operations/instance_operation.ex @@ -137,7 +137,7 @@ defmodule Pleroma.Web.ApiSpec.InstanceOperation do "background_upload_limit" => 4_000_000, "background_image" => "/static/image.png", "banner_upload_limit" => 4_000_000, - "description" => "Pleroma: An efficient and flexible fediverse server", + "description" => "Akkoma: The cooler fediverse server", "email" => "lain@lain.com", "languages" => ["en"], "max_toot_chars" => 5000, @@ -160,7 +160,7 @@ defmodule Pleroma.Web.ApiSpec.InstanceOperation do "urls" => %{ "streaming_api" => "wss://lain.com" }, - "version" => "2.7.2 (compatible; Pleroma 2.0.50-536-g25eec6d7-develop)" + "version" => "2.7.2 (compatible; Akkoma 3.9.3-232-g6fde75e1-develop)" } } end