Explain how federation works for admins, various doc updates (#1176)

docs/src/SUMMARY.md

@@ -10,6 +10,7 @@
   - [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)

docs/src/administration_federation.md

@@ -0,0 +1,27 @@
+# Federation 
+
+Note: ActivityPub federation is still under development. We recommend that you only enable it on test instances for now.
+
+To enable federation, change the setting `federation.enabled` to `true` in `lemmy.hjson`, and restart Lemmy.
+
+Federation does not start automatically, but needs to be triggered manually through the search. To do this you have to enter a reference to a remote object, such as:
+
+- `!main@dev.lemmy.ml` (Community)
+- `@nutomic@dev.lemmy.ml` (User)
+- `https://dev.lemmy.ml/c/programming` (Community)
+- `https://dev.lemmy.ml/u/nutomic` (User)
+- `https://dev.lemmy.ml/post/123` (Post)
+
+For an overview of how federation in Lemmy works on a technical level, check out our [Federation Overview](contributing_federation_overview.md).
+
+## Instance allowlist and blocklist
+
+The federation section of Lemmy's config has two variables `allowed_instances` and `blocked_instances`. These control which other instances Lemmy will federate with. Both settings take a comma separated list of domains, eg `dev.lemmy.ml, example.com`. You can either change those settings via `/admin`, or directly on the server filesystem. 
+
+It is important to note that these settings only affect sending and receiving of data between instances. If allow federation with a certain instance, and then remove it from the allowlist, this will not affect previously federated data. These communities, users, posts and comments will still be shown. They will just not be updated anymore. And even if an instance is blocked, it can still fetch and display public data from your instance.
+
+By default, both `allowed_instances` and `blocked_instances` values are empty, which means that Lemmy will federate with every compatible instance. We do not recommend this, because the moderation tools are not yet ready to deal with malicious instances.
+
+What we do recommend is putting a list of trusted instances into `allowed_instances`, and only federating with those. Note that both sides need to add each other to their `allowed_instances` to allow two-way federation.
+
+Alternatively you can also use blocklist based federation. In this case, add the domains of instances you do *not* want to federate with. You can only set one of `allowed_instances` and `blocked_instances`, as setting both doesn't make sense.

docs/src/contributing_docker_development.md

@@ -11,8 +11,8 @@ git clone https://github.com/LemmyNet/lemmy
 ## Running
 
 ```bash
-cd lemmy/docker/dev
+cd /docker/dev
-sudo docker-compose up --no-deps --build
+./docker_update.sh
 ```
 
 and go to http://localhost:1235.

docs/src/contributing_local_development.md

@@ -36,6 +36,9 @@ cargo build
 ### Get the front end source code
 ```
 git clone https://github.com/LemmyNet/lemmy-ui.git
+# get the translations
+git submodule init
+git submodule update
 ```
 
 ### Setup postgresql