Merge pull request 'Rewrite federation docs' (#145) from federation-docs into main

Reviewed-on: https://yerbamate.ml/LemmyNet/lemmy/pulls/145

docs/src/SUMMARY.md

@@ -1,23 +1,25 @@
 # Summary
 
-- [About](about.md)
-  - [Features](about_features.md)
-  - [Goals](about_goals.md)
-  - [Post and Comment Ranking](about_ranking.md)
-  - [Guide](about_guide.md)
-- [Administration](administration.md)
-  - [Install with Docker](administration_install_docker.md)
-  - [Install with Ansible](administration_install_ansible.md)
-  - [Configuration](administration_configuration.md)
-  - [Backup and Restore](administration_backup_and_restore.md)
-  - [Federation](administration_federation.md)
-- [Contributing](contributing.md)
-  - [Docker Development](contributing_docker_development.md)
-  - [Local Development](contributing_local_development.md)
-  - [Tests](contributing_tests.md)
-  - [Federation Development](contributing_federation_development.md)
-  - [Websocket/HTTP API](contributing_websocket_http_api.md)
-  - [Federation Overview](contributing_federation_overview.md)
-  - [ActivityPub API Outline](contributing_apub_api_outline.md)
-  - [Theming Guide](contributing_theming.md)
+- [About](about/about.md)
+  - [Features](about/features.md)
+  - [Goals](about/goals.md)
+  - [Post and Comment Ranking](about/ranking.md)
+  - [Guide](about/guide.md)
+- [Administration](administration/administration.md)
+  - [Install with Docker](administration/install_docker.md)
+  - [Install with Ansible](administration/install_ansible.md)
+  - [Configuration](administration/configuration.md)
+  - [Backup and Restore](administration/backup_and_restore.md)
+- [Federation](federation/federation.md)
+  - [Federation Overview](federation/overview.md)
+  - [Administration](federation/administration.md)
+  - [Resources](federation/resources.md)
+  - [Lemmy Protocol](federation/lemmy_protocol.md)
+- [Contributing](contributing/contributing.md)
+  - [Docker Development](contributing/docker_development.md)
+  - [Local Development](contributing/local_development.md)
+  - [Theming Guide](contributing/theming.md)
+  - [Tests](contributing/tests.md)
+  - [Websocket/HTTP API](contributing/websocket_http_api.md)
+  - [Federation Development](contributing/federation_development.md)
 - [Lemmy Council](lemmy_council.md)

docs/src/about/goals.md

@@ -36,19 +36,3 @@
 - [Rust docker build](https://shaneutt.com/blog/rust-fast-small-docker-image-builds/)
 - [Zurb mentions](https://github.com/zurb/tribute)
 - [TippyJS](https://github.com/atomiks/tippyjs)
-
-## Activitypub guides
-
-- https://blog.joinmastodon.org/2018/06/how-to-implement-a-basic-activitypub-server/
-- https://raw.githubusercontent.com/w3c/activitypub/gh-pages/activitypub-tutorial.txt
-- https://github.com/tOkeshu/activitypub-example
-- https://blog.joinmastodon.org/2018/07/how-to-make-friends-and-verify-requests/
-- Use the [activitypub crate.](https://docs.rs/activitypub/0.1.4/activitypub/)
-- https://docs.rs/activitypub/0.1.4/activitypub/
-- [Activitypub vocab.](https://www.w3.org/TR/activitystreams-vocabulary/)
-- [Activitypub main](https://www.w3.org/TR/activitypub/)
-- [Federation.md](https://github.com/dariusk/gathio/blob/7fc93dbe9d4d99457a0e85c6c532112f415b7af2/FEDERATION.md)
-- [Activitypub implementers guide](https://socialhub.activitypub.rocks/t/draft-guide-for-new-activitypub-implementers/479)
-- [Data storage questions](https://socialhub.activitypub.rocks/t/data-storage-questions/579/3)
-- [Activitypub as it has been understood](https://flak.tedunangst.com/post/ActivityPub-as-it-has-been-understood)
-- [Asonix http signatures in rust](https://git.asonix.dog/Aardwolf/http-signature-normalization)

docs/src/about/guide.md

@@ -17,7 +17,7 @@ Hot | Trending sort based on the score, and the post creation time.
 New | Newest items.
 Top | The highest scoring items in the given time frame.
 
-For more detail, check the [Post and Comment Ranking details](about_ranking.md).
+For more detail, check the [Post and Comment Ranking details](ranking.md).
 
 ## Markdown Guide
 

docs/src/administration/administration.md

@@ -4,7 +4,7 @@ Information for Lemmy instance admins, and those who want to run a server.
 
 ## Install
 
-Lemmy has two primary install methods, [docker](administration_install_docker.md), and [ansible](administration_install_ansible.md). Ansible simplifies deploying to a remote server, while docker is best for local testing.
+Lemmy has two primary install methods, [docker](install_docker.md), and [ansible](install_ansible.md). Ansible simplifies deploying to a remote server, while docker is best for local testing.
 
 ### Manual install
 

docs/src/administration/install_ansible.md

@@ -1,6 +1,6 @@
 # Ansible Installation
 
-This is the same as the [Docker installation](administration_install_docker.md), except that Ansible handles all of it automatically. It also does some extra things like setting up TLS and email for your Lemmy instance.
+This is the same as the [Docker installation](install_docker.md), except that Ansible handles all of it automatically. It also does some extra things like setting up TLS and email for your Lemmy instance.
 
 First, you need to [install Ansible on your local computer](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) (e.g. using `sudo apt install ansible`) or the equivalent for you platform.
 

docs/src/administration/install_docker.md

@@ -27,7 +27,7 @@ Open up your `docker-compose.yml`, and make sure `LEMMY_EXTERNAL_HOST` for `lemm
 
 If you'd like a different database password, you should also change it in the `docker-compose.yml` **before** your first run.
 
-After this, have a look at the [config file](administration_configuration.md) named `lemmy.hjson`, and adjust it, in particular the hostname, and possibly the db password. Then run:
+After this, have a look at the [config file](configuration.md) named `lemmy.hjson`, and adjust it, in particular the hostname, and possibly the db password. Then run:
 
 `docker-compose up -d`
 

docs/src/contributing/docker_development.md

@@ -29,4 +29,4 @@ To speed up the Docker compile, add the following to `/etc/docker/daemon.json` a
 ```
 
 If the build is still too slow, you will have to use a
-[local build](contributing_local_development.md) instead.
+[local build](local_development.md) instead.

docs/src/contributing/federation_development.md

@@ -2,7 +2,7 @@
 
 ## Running locally
 
-Install the dependencies as described in [Docker development](contributing_docker_development.md). Then run the following
+Install the dependencies as described in [Docker development](docker_development.md). Then run the following
 
 ```bash
 cd docker/federation
@@ -34,8 +34,8 @@ Firefox containers are a good way to test them interacting.
 
 Note that federation is currently in alpha. **Only use it for testing**, not on any production server, and be aware that turning on federation may break your instance.
 
-Follow the normal installation instructions, either with [Ansible](administration_install_ansible.md) or
-[manually](administration_install_docker.md). Then replace the line `image: dessalines/lemmy:v0.x.x` in 
+Follow the normal installation instructions, either with [Ansible](../administration/install_ansible.md) or
+[manually](../administration/install_docker.md). Then replace the line `image: dessalines/lemmy:v0.x.x` in 
 `/lemmy/docker-compose.yml` with `image: dessalines/lemmy:federation`. Also add the following in
 `/lemmy/lemmy.hjson`:
 

docs/src/contributing/local_development.md

@@ -85,4 +85,4 @@ and go to [localhost:1234](http://localhost:1234). Front end saves should rebuil
 
 Note that this setup doesn't include image uploads or link previews (provided by pict-rs and
 iframely respectively). If you want to test those, you should use the
-[Docker development](contributing_docker_development.md).
+[Docker development](docker_development.md).

docs/src/contributing/tests.md

@@ -2,7 +2,7 @@
 
 #### Rust
 
-After installing [local development dependencies](contributing_local_development.md), run the
+After installing [local development dependencies](local_development.md), run the
 following commands:
 
 ```bash
@@ -12,7 +12,7 @@ psql -U lemmy -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
 
 ### Federation
 
-Install the [Docker development dependencies](contributing_docker_development.md), and execute:
+Install the [Docker development dependencies](docker_development.md), and execute:
 
 ```
 cd docker/federation

docs/src/federation/administration.md

@@ -1,4 +1,4 @@
-# Federation 
+# Federation Administration
 
 Note: ActivityPub federation is still under development. We recommend that you only enable it on test instances for now.
 
@@ -11,6 +11,7 @@ Federation does not start automatically, but needs to be triggered manually thro
 - `https://lemmy.ml/c/programming` (Community)
 - `https://lemmy.ml/u/nutomic` (User)
 - `https://lemmy.ml/post/123` (Post)
+- `https://lemmy.ml/comment/321` (Comment)
 
 For an overview of how federation in Lemmy works on a technical level, check out our [Federation Overview](contributing_federation_overview.md).
 

docs/src/federation/federation.md

@@ -0,0 +1,14 @@
+# Federation
+
+Lemmy uses the ActivityPub protocol (a W3C standard) to enable federation between different servers (often called instances). This is very similar to the way email works. For example, if you use gmail.com, then you can't just send mails to other gmail.com users, but also to yahoo.com, yandex.ru and so on. Email uses the SMTP protocol to achieve this, so you can think of ActivityPub as "SMTP for social media". The amount of different actions possible on social media (post, comment, like, share, etc) means that ActivityPub is much more complicated than SMTP.
+
+As with email, ActivityPub federation happens only between servers. So if you are registered on `enterprise.lemmy.ml`, you only connect to the API of `enterprise.lemmy.ml`, while the server takes care of sending and receiving data from other instances (eg `voyager.lemmy.ml`). The great advantage of this approach is that the average user doesn't have to do anything to use federation. In fact if you are using Lemmy, you are likely already using it. One way to confirm is by going to a community or user profile. If you are on `enterprise.lemmy.ml` and you see a user like `@nutomic@voyager.lemmy.ml`, or a community like `!main@ds9.lemmy.ml`, then those are federated, meaning they use a different instance from yours.
+
+One way you can take advantage of federation is by opening a different instance, like `ds9.lemmy.ml`, and browsing it. If you see an interesting community, post or user that you want to interact with, just copy its URL and paste it into the search of your own instance. Your instance will connect to the other one (assuming the allowlist/blocklist allows it), and directly display the remote content to you, so that you can follow a community or comment on a post. Here are some examples of working searches:
+
+- `!main@lemmy.ml` (Community)
+- `@nutomic@lemmy.ml` (User)
+- `https://lemmy.ml/c/programming` (Community)
+- `https://lemmy.ml/u/nutomic` (User)
+- `https://lemmy.ml/post/123` (Post)
+- `https://lemmy.ml/comment/321` (Comment)

docs/src/federation/lemmy_protocol.md

@@ -1,4 +1,6 @@
-# Activitypub API outline
+# Lemmy Federation Protocol
+
+The Lemmy Protocol (or Lemmy Federation Protocol) is a strict subset of the [ActivityPub Protocol](https://www.w3.org/TR/activitypub/). Any deviation from the ActivityPub protocol is a bug in Lemmy or in this documentation (or both).
 
 This document is targeted at developers who are familiar with the ActivityPub and ActivityStreams protocols. It gives a detailed outline of the actors, objects and activities used by Lemmy.
 

docs/src/federation/overview.md

@@ -1,4 +1,4 @@
-# Federation
+# Federation Overview
 
 
 This document is for anyone who wants to know how Lemmy federation works, without being overly technical. It is meant provide a high-level overview of ActivityPub federation in Lemmy. If you are implementing ActivityPub yourself and want to be compatible with Lemmy, read our [ActivityPub API outline](contributing_apub_api_outline.md).

docs/src/federation/resources.md

@@ -0,0 +1,22 @@
+# ActivityPub Resources
+
+## Official Documents
+
+- [ActivityPub standard](https://www.w3.org/TR/activitypub/)
+- [Activitypub vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/)
+
+## Explanations
+
+- [ActivityPub - one protocol to rule them all?](https://schub.io/blog/2018/02/01/activitypub-one-protocol-to-rule-them-all.html)
+- [A highly opinionated guide to learning about ActivityPub](https://tinysubversions.com/notes/reading-activitypub/)
+- [Activitypub implementers guide](https://socialhub.activitypub.rocks/t/draft-guide-for-new-activitypub-implementers/479)
+- [Mastodon Blog: How to implement a basic ActivityPub server](https://blog.joinmastodon.org/2018/06/how-to-implement-a-basic-activitypub-server/)
+- [Mastodon Blog: Implementing an ActivityPub inbox](https://blog.joinmastodon.org/2018/07/how-to-make-friends-and-verify-requests/)
+- [Data storage questions](https://socialhub.activitypub.rocks/t/data-storage-questions/579)
+- [Activitypub as it has been understood](https://flak.tedunangst.com/post/ActivityPub-as-it-has-been-understood)
+
+## Examples and Libraries
+
+- [ActivityPub example server](https://github.com/tOkeshu/activitypub-example)
+- [ActivityStreams crate](https://docs.rs/activitystreams/)
+- [HTTP Signatures crate](https://git.asonix.dog/Aardwolf/http-signature-normalization)