]> Untitled Git - lemmy.git/commitdiff
Rewrite federation docs
authorFelix Ableitner <me@nutomic.com>
Sun, 29 Nov 2020 12:09:14 +0000 (13:09 +0100)
committerFelix Ableitner <me@nutomic.com>
Tue, 8 Dec 2020 13:52:54 +0000 (14:52 +0100)
23 files changed:
docs/src/SUMMARY.md
docs/src/about/about.md [moved from docs/src/about.md with 100% similarity]
docs/src/about/features.md [moved from docs/src/about_features.md with 100% similarity]
docs/src/about/goals.md [moved from docs/src/about_goals.md with 69% similarity]
docs/src/about/guide.md [moved from docs/src/about_guide.md with 96% similarity]
docs/src/about/ranking.md [moved from docs/src/about_ranking.md with 100% similarity]
docs/src/administration/administration.md [moved from docs/src/administration.md with 73% similarity]
docs/src/administration/backup_and_restore.md [moved from docs/src/administration_backup_and_restore.md with 100% similarity]
docs/src/administration/configuration.md [moved from docs/src/administration_configuration.md with 100% similarity]
docs/src/administration/install_ansible.md [moved from docs/src/administration_install_ansible.md with 78% similarity]
docs/src/administration/install_docker.md [moved from docs/src/administration_install_docker.md with 91% similarity]
docs/src/contributing/contributing.md [moved from docs/src/contributing.md with 100% similarity]
docs/src/contributing/docker_development.md [moved from docs/src/contributing_docker_development.md with 91% similarity]
docs/src/contributing/federation_development.md [moved from docs/src/contributing_federation_development.md with 91% similarity]
docs/src/contributing/local_development.md [moved from docs/src/contributing_local_development.md with 97% similarity]
docs/src/contributing/tests.md [moved from docs/src/contributing_tests.md with 51% similarity]
docs/src/contributing/theming.md [moved from docs/src/contributing_theming.md with 100% similarity]
docs/src/contributing/websocket_http_api.md [moved from docs/src/contributing_websocket_http_api.md with 100% similarity]
docs/src/federation/administration.md [moved from docs/src/administration_federation.md with 96% similarity]
docs/src/federation/federation.md [new file with mode: 0644]
docs/src/federation/lemmy_protocol.md [moved from docs/src/contributing_apub_api_outline.md with 98% similarity]
docs/src/federation/overview.md [moved from docs/src/contributing_federation_overview.md with 99% similarity]
docs/src/federation/resources.md [new file with mode: 0644]

index e00f5ced60067c81369a3e695f9ce54899591fbb..93f6c42d0692f9cd8a5abd6123983989b8ba78e8 100644 (file)
@@ -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)
similarity index 100%
rename from docs/src/about.md
rename to docs/src/about/about.md
similarity index 69%
rename from docs/src/about_goals.md
rename to docs/src/about/goals.md
index e0427481c1dfe7912763d8d0d8eb71bbef922fee..e7d8e8dc6b2a72f51a8c737481c9dfe9a3305e91 100644 (file)
 - [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)
similarity index 96%
rename from docs/src/about_guide.md
rename to docs/src/about/guide.md
index d9f8adb0dee26dd48859b9e0645c84a3474844fd..59244b1e87fcd8365d5deb5ba2d6ada312fde0af 100644 (file)
@@ -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
 
similarity index 73%
rename from docs/src/administration.md
rename to docs/src/administration/administration.md
index 690b71596e6f594a0f2ad94f904c529f4ffb0147..3211859bf17580fedae91e926e025988309ecb49 100644 (file)
@@ -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
 
similarity index 78%
rename from docs/src/administration_install_ansible.md
rename to docs/src/administration/install_ansible.md
index 849957ad10910bdd2ddc4b699cc1f092dd1be54a..ea04f53d0f5de360720e7746d6d67379a448e1a0 100644 (file)
@@ -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.
 
similarity index 91%
rename from docs/src/administration_install_docker.md
rename to docs/src/administration/install_docker.md
index 490fe1c01034023793c88beead6488132e52923d..4796fe528d9f04cab5dab8d33712288402e05857 100644 (file)
@@ -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`
 
similarity index 91%
rename from docs/src/contributing_docker_development.md
rename to docs/src/contributing/docker_development.md
index 3272efe247c67deb263d46df8a3db165261937d1..ee035dd2ba1afcda11752dbd5c44521df1515f0d 100644 (file)
@@ -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.
similarity index 91%
rename from docs/src/contributing_federation_development.md
rename to docs/src/contributing/federation_development.md
index 0c6fd9c4047613922ab5f8b8c3a166eb05cc1783..fd625d60d6c4f795a02e9275d46e3fd89b93d4ad 100644 (file)
@@ -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`:
 
similarity index 97%
rename from docs/src/contributing_local_development.md
rename to docs/src/contributing/local_development.md
index ccf1f51eebae924090efe1fb6c04aded810b0158..114a5458420bc86943946de1f8728717bc793977 100644 (file)
@@ -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).
similarity index 51%
rename from docs/src/contributing_tests.md
rename to docs/src/contributing/tests.md
index 494cf5cd949a79882d669bb05a0235baa18127c1..e4cfa65a90595731192d377d8fabf5c41a6dcaf5 100644 (file)
@@ -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
similarity index 96%
rename from docs/src/administration_federation.md
rename to docs/src/federation/administration.md
index c7044ac2484da22289f7a42536b5bad674267572..fc24216c81518467b38caa5b9e3ed97cc0285305 100644 (file)
@@ -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).
 
diff --git a/docs/src/federation/federation.md b/docs/src/federation/federation.md
new file mode 100644 (file)
index 0000000..28e304d
--- /dev/null
@@ -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)
\ No newline at end of file
similarity index 98%
rename from docs/src/contributing_apub_api_outline.md
rename to docs/src/federation/lemmy_protocol.md
index 92cdf9c0e7fff32fc85e3674b946287aa955e620..75dfe263469aba85cec9e8fe45bd7fc1e39da8f9 100644 (file)
@@ -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.
 
similarity index 99%
rename from docs/src/contributing_federation_overview.md
rename to docs/src/federation/overview.md
index abfac4552a919813e7622f5b75694dda830a6be3..949984b8a12bb03fe2759dcfb5f04383a002cdab 100644 (file)
@@ -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).
diff --git a/docs/src/federation/resources.md b/docs/src/federation/resources.md
new file mode 100644 (file)
index 0000000..0f14691
--- /dev/null
@@ -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)
\ No newline at end of file