nrd.li/akkoma
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge pull request 'Update development docs' (#43) from norm/akkoma:docs-development into develop

Browse source 
Reviewed-on: https://akkoma.dev/AkkomaGang/akkoma/pulls/43
This commit is contained in:
floatingghost 2022-07-04 15:49:08 +00:00
parent 01652167d0 5e02658e55
commit 87bb417c99
6 changed files with 31 additions and 31 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/development/API/chats.md
View file

@ -13,7 +13,7 @@ This is an awkward setup for a few reasons:
- The standard `Status` format of implicit addressing also leads to rather ugly results if you try to display the messages as a chat, because all the recipients are always mentioned by name in the message.
- As direct messages are posted with the same api call (and usually same frontend component) as public messages, accidentally making a public message private or vice versa can happen easily. Client bugs can also lead to this, accidentally making private messages public.
As a measure to improve this situation, the `Conversation` concept and related Pleroma extensions were introduced. While it made it possible to work around a few of the issues, many of the problems remained and it didn't see much adoption because it was too complicated to use correctly.
As a measure to improve this situation, the `Conversation` concept and related Akkoma extensions were introduced. While it made it possible to work around a few of the issues, many of the problems remained and it didn't see much adoption because it was too complicated to use correctly.
## Chats explained
For this reasons, Chats are a new and different entity, both in the API as well as in ActivityPub. A quick overview:

24
docs/development/API/differences_in_mastoapi_responses.md
View file

@ -1,10 +1,10 @@
# Differences in Mastodon API responses from vanilla Mastodon
A Pleroma instance can be identified by "<Mastodon version> (compatible; Pleroma <version>)" present in `version` field in response from `/api/v1/instance`
A Akkoma instance can be identified by "<Mastodon version> (compatible; Pleroma <version>)" present in `version` field in response from `/api/v1/instance`
## Flake IDs
Pleroma uses 128-bit ids as opposed to Mastodon's 64 bits. However, just like Mastodon's ids, they are lexically sortable strings
Akkoma uses 128-bit ids as opposed to Mastodon's 64 bits. However, just like Mastodon's ids, they are lexically sortable strings
## Timelines
@ -54,11 +54,11 @@ Has these additional fields under the `pleroma` object:
### Attachment cap
Some apps operate under the assumption that no more than 4 attachments can be returned or uploaded. Pleroma however does not enforce any limits on attachment count neither when returning the status object nor when posting.
Some apps operate under the assumption that no more than 4 attachments can be returned or uploaded. Akkoma however does not enforce any limits on attachment count neither when returning the status object nor when posting.
### Limitations
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.
Akkoma 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.
## Accounts
@ -99,7 +99,7 @@ Has these additional fields under the `pleroma` object:
- `hide_followers_count`: boolean, true when the user has follower stat hiding enabled
- `hide_follows_count`: boolean, true when the user has follow stat hiding enabled
- `settings_store`: A generic map of settings for frontends. Opaque to the backend. Only returned in `/api/v1/accounts/verify_credentials` and `/api/v1/accounts/update_credentials`
- `chat_token`: The token needed for Pleroma shoutbox. Only returned in `/api/v1/accounts/verify_credentials`
- `chat_token`: The token needed for Akkoma shoutbox. Only returned in `/api/v1/accounts/verify_credentials`
- `deactivated`: boolean, true when the user is deactivated
- `allow_following_move`: boolean, true when the user allows automatically follow moved following accounts
- `unread_conversation_count`: The count of unread conversations. Only returned to the account owner.
@ -245,9 +245,9 @@ Additional parameters can be added to the JSON body/Form data:
All images (avatar, banner and background) can be reset to the default by sending an empty string ("") instead of a file.
### Pleroma Settings Store
### Akkoma Settings Store
Pleroma has mechanism that allows frontends to save blobs of json for each user on the backend. This can be used to save frontend-specific settings for a user that the backend does not need to know about.
Akkoma has mechanism that allows frontends to save blobs of json for each user on the backend. This can be used to save frontend-specific settings for a user that the backend does not need to know about.
The parameter should have a form of `{frontend_name: {...}}`, with `frontend_name` identifying your type of client, e.g. `pleroma_fe`. It will overwrite everything under this property, but will not overwrite other frontend's settings.
@ -255,7 +255,7 @@ This information is returned in the `/api/v1/accounts/verify_credentials` endpoi
## Authentication
*Pleroma supports refreshing tokens.*
*Akkoma supports refreshing tokens.*
### POST `/oauth/token`
@ -278,14 +278,14 @@ To obtain a token from a user's password, pass `grant_type=password` with the fo
Additional fields are returned in the response:
- `id`: The primary key of this token in Pleroma's database.
- `id`: The primary key of this token in Akkoma's database.
- `me` (user tokens only): The ActivityPub ID of the user who owns the token.
## Account Registration
`POST /api/v1/accounts`
Has these additional parameters (which are the same as in Pleroma-API):
Has these additional parameters (which are the same as in Akkoma-API):
- `fullname`: optional
- `bio`: optional
@ -342,7 +342,7 @@ For viewing remote server timelines, there are `public:remote` and `public:remot
### Follow relationships updates
Pleroma streams follow relationships updates as `pleroma:follow_relationships_update` events to the `user` stream.
Akkoma streams follow relationships updates as `pleroma:follow_relationships_update` events to the `user` stream.
The message payload consist of:
@ -359,7 +359,7 @@ Both user muting and thread muting can be done for only a certain time by adding
## 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.
Akkoma 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.
### Suggestions

4
docs/development/API/nodeinfo.md
View file

@ -330,8 +330,8 @@ See also [the Nodeinfo standard](https://nodeinfo.diaspora.software/).
},
"software":{
"name":"pleroma",
"repository":"https://git.pleroma.social/pleroma/pleroma",
"version":"2.4.1"
"repository":"https://akkoma.dev/AkkomaGang/akkoma",
"version":"2.5.2"
},
"usage":{
"localPosts":27,

6
docs/development/API/prometheus.md
View file

@ -1,6 +1,6 @@
# Prometheus Metrics
Pleroma includes support for exporting metrics via the [prometheus_ex](https://github.com/deadtrickster/prometheus.ex) library.
Akkoma includes support for exporting metrics via the [prometheus_ex](https://github.com/deadtrickster/prometheus.ex) library.
Config example:
@ -13,8 +13,8 @@ config :prometheus, Pleroma.Web.Endpoint.MetricsExporter,
format: :text
```
* `enabled` (Pleroma extension) enables the endpoint
* `ip_whitelist` (Pleroma extension) could be used to restrict access only to specified IPs
* `enabled` (Akkoma extension) enables the endpoint
* `ip_whitelist` (Akkoma 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

2
docs/development/authentication_authorization.md
View file

@ -2,7 +2,7 @@
## OAuth token-based authentication & authorization
* Pleroma supports hierarchical OAuth scopes, just like Mastodon but with added granularity of admin scopes. For a reference, see [Mastodon OAuth scopes](https://docs.joinmastodon.org/api/oauth-scopes/).
* Akkoma supports hierarchical OAuth scopes, just like Mastodon but with added granularity of admin scopes. For a reference, see [Mastodon OAuth scopes](https://docs.joinmastodon.org/api/oauth-scopes/).
* It is important to either define OAuth scope restrictions or explicitly mark OAuth scope check as skipped, for every controller action. To define scopes, call `plug(Pleroma.Web.Plugs.OAuthScopesPlug, %{scopes: [...]})`. To explicitly set OAuth scopes check skipped, call `plug(:skip_plug, Pleroma.Web.Plugs.OAuthScopesPlug <when ...>)`.

24
docs/development/setting_up_pleroma_dev.md → docs/development/setting_up_akkoma_dev.md
View file

@ -1,13 +1,13 @@
# Setting up a Pleroma development environment
# Setting up a Akkoma development environment
Pleroma requires some adjustments from the defaults for running the instance locally. The following should help you to get started.
Akkoma requires some adjustments from the defaults for running the instance locally. The following should help you to get started.
## Installing
1. Install Pleroma as explained in [the docs](../installation/debian_based_en.md), with some exceptions:
* You can use your own fork of the repository and add pleroma as a remote `git remote add pleroma 'https://git.pleroma.social/pleroma/pleroma'`
1. Install Akkoma as explained in [the docs](../installation/debian_based_en.md), with some exceptions:
* You can use your own fork of the repository and add akkoma as a remote `git remote add akkoma 'https://akkoma.dev/AkkomaGang/akkoma.git'`
* You can skip systemd and nginx and all that stuff
* No need to create a dedicated pleroma user, it's easier to just use your own user
* No need to create a dedicated akkoma user, it's easier to just use your own user
* For the DB you can still choose a dedicated user, the mix tasks set it up for you so it's no extra work for you
* For domain you can use `localhost`
* instead of creating a `prod.secret.exs`, create `dev.secret.exs`
@ -40,13 +40,13 @@ config :logger, :console,
1. Create a `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;"`
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. 'akkoma_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 akkoma_local_test WITH CREATEDB;"`
3. Run the tests with `mix test`. The tests should succeed.
Example content for the `test.secret.exs` file. Feel free to use another user, database name or password, just make sure the database is dedicated for the testing environment.
```elixir
# Pleroma test configuration
# Akkoma test configuration
# NOTE: This file should not be committed to a repo or otherwise made public
# without removing sensitive information.
@ -54,17 +54,17 @@ Example content for the `test.secret.exs` file. Feel free to use another user, d
import Config
config :pleroma, Pleroma.Repo,
username: "pleroma_local_test",
username: "akkoma_local_test",
password: "mysuperduperpassword",
database: "pleroma_local_test",
database: "akkoma_local_test",
hostname: "localhost"
```
## Updating
Update Pleroma as explained in [the docs](../administration/updating.md). Just make sure you pull from upstream and not from your own fork.
Update Akkoma as explained in [the docs](../administration/updating.md). Just make sure you pull from upstream and not from your own fork.
## Working on multiple branches
If you develop on a separate branch, it's possible you did migrations that aren't merged into another branch you're working on. If you have multiple things you're working on, it's probably best to set up multiple pleroma's each with their own database. If you finished with a branch and want to switch back to develop to start a new branch from there, you can drop the database and recreate the database (e.g. by using `config/setup_db.psql`). The commands to drop and recreate the database can be found in [the docs](../administration/backup.md).
If you develop on a separate branch, it's possible you did migrations that aren't merged into another branch you're working on. If you have multiple things you're working on, it's probably best to set up multiple Akkoma instances each with their own database. If you finished with a branch and want to switch back to develop to start a new branch from there, you can drop the database and recreate the database (e.g. by using `config/setup_db.psql`). The commands to drop and recreate the database can be found in [the docs](../administration/backup.md).