Added basic documentation on the federation feature

docs/features.rst

@@ -42,3 +42,14 @@ The project itself is splitted in two parts:
 While the main interface to the server and API is the bundled front-end, the project itself is agnostic in the way you connect to it. Therefore, desktop clients or apps could be developped and implement the same (or even more) features as the bundled frontend.
 
 This modularity also makes it possible do deploy only a single component from the system.
+
+Federation
+----------
+
+Each Funkwhale instance is able to fetch music from other compatible servers,
+and share its own library on the network. The federation is implemented
+using the ActivityPub protocol, in order to leverage existing tools
+and be compatible with other services such as Mastodon.
+
+As of today, federation only targets music acquisition, meaning user interaction
+are not shared via ActivityPub. This will be implemented at a later point.

docs/federation.rst

@@ -0,0 +1,40 @@
+Federation
+==========
+
+Each Funkwale instance can federates its music library with other instances
+of the network. This means that an instance A can acquire music from instance B
+and share its own library with an instance C.
+
+We support various levels of controls for federation-related features.
+
+Acquire music via federation
+----------------------------
+
+Instance libraries are protected by default. To access another instance
+library, you have to follow it. This follow request will be sent to
+the other instance which can accept or deny it. Once your follow request
+is accepted, you can start browsing the other instance library
+and import music from it.
+
+By default, we do not duplicate audio files from federated tracks, to reduce
+disk usage on your instance. When someone listens to a federated track,
+the audio file is requested on the fly from the remote instance, and
+store in a local cache. It is automatically deleted after a configurable
+amount of time if it was not listened again in the meantime.
+
+If you want to mirror a remote instance collection, including its audio files,
+we offer an option for that.
+
+We also support an "autoimport" mode for each remote library. When enabled,
+any new track published in the remote library will be directly imported
+in your instance.
+
+Share music via federation
+--------------------------
+
+Federation is enabled by default, but requires manually approving
+each other instance asking for access to library. This is by design,
+to ensure your library is not shared publicly without your consent.
+
+However, we offer a configuration option to alter this behaviour and
+disable the manual approval part.

docs/importing-music.rst

@@ -67,3 +67,9 @@ under creative commons (courtesy of Jamendo):
     ./download-tracks.sh music.txt
 
 This will download a bunch of zip archives (one per album) under the ``data/music`` directory and unzip their content.
+
+From other instances
+--------------------
+
+Funkwhale also supports importing music from other instances. Please refer
+to :doc:`federation` for more details.

docs/index.rst

@@ -15,6 +15,7 @@ Funkwhale is a self-hosted, modern free and open-source music server, heavily in
    installation/index
    configuration
    importing-music
+   federation
    upgrading
    changelog