# 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)
- [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)
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
## 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
# 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.
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`
```
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.
## 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
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`:
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).
#### 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
### 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
-# Federation
+# Federation Administration
Note: ActivityPub federation is still under development. We recommend that you only enable it on test instances for now.
- `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).
--- /dev/null
+# 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
-# 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.
-# 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).
--- /dev/null
+# 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
projects / lemmy.git / commitdiff