From a00e16270cb60cf8bf9075eb8bf46b7c3baf8bba Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Blin?=
 <sebastien.blin@savoirfairelinux.com>
Date: Fri, 4 Nov 2022 07:48:29 -0400
Subject: [PATCH] user: add documentation to run jami over a LAN

Change-Id: I395a2639b1bc8d904914da2e6ea6787784439a6e
---
 user/index.rst    |  1 +
 user/lan-only.rst | 76 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 user/lan-only.rst

diff --git a/user/index.rst b/user/index.rst
index b92b8850..5da49014 100644
--- a/user/index.rst
+++ b/user/index.rst
@@ -18,6 +18,7 @@ bugs and issues.
    features
    all-features-by-client
    faq
+   lan-only
    tutorials
    bug-report-guide
 
diff --git a/user/lan-only.rst b/user/lan-only.rst
new file mode 100644
index 00000000..60d38b3d
--- /dev/null
+++ b/user/lan-only.rst
@@ -0,0 +1,76 @@
+Use Jami on a LAN
+=================
+
+Due the distributed nature of Jami, it is possible to use it over a LAN,
+without any Internet connection. This allows you to continue to communicate
+with other people in the company/building/country without global Internet
+access. However, some services are external so in this document we will
+explain some tweaks you may need.
+
+.. contents::
+   :local:
+   :depth: 3
+
+
+Boostraping
+-----------
+
+What is a bootstrap?
+~~~~~~~~~~~~~~~~~~~~
+
+Jami uses the DHT technology to find other users. So, all the users you want
+to contact must be reachable on the same DHT network (e.g. if the Internet is split
+between two buildings, users in the first buildings will not be able to reach the
+second building). To enter a DHT network, one must be able to reach at least one
+other node. This node is called bootstrap, it is the entry point of the network. By
+default, **bootstrap.jami.net** is configured, but any node in the public DHT can be a
+bootstrap (it is a classic node, generally always online).
+
+So, if the Internet is cut, you need another bootstrap to create a network. On a LAN,
+there is two ways to configure it in Jami:
+
+Bootstrap settings
+~~~~~~~~~~~~~~~~~~
+
+In the advanced account settings, the user can configure multiple bootstraps.
+**bootstrap.jami.net** is usually the default, **bootstrap.jami.net;your.bootstrap.tld**
+will be valid. The IP:port of another DHT node can be specified as a bootstrap.
+
+Local Peer Discovery
+~~~~~~~~~~~~~~~~~~~~
+
+Another way is to enable peer discovery. This will announce the bootstrap on the network
+by broadcasting UDP packets (like a printer). So, UDP broadcast must be supported by the
+network in order to work. However, this method does not need to specify an ip:port in the
+settings, so it can be preferred.
+
+TURN
+----
+
+Another external service is the TURN server, used as a fallback for connections if the NAT
+block all possible connections. Generally it is **turn.jami.net** but can be any TURN (we use
+coturn, cf. :doc:`/developer/setting-up-your-own-turn-server`)
+
+On a LAN, it may be ignored (because there will be no NAT), but disabling it should not
+be necessary (because it will not be used if unreachable).
+
+On mobile (DHT Proxy)
+---------------------
+
+A DHT Proxy is used with mobile devices to save battery by avoiding synchronization. It is generally
+**dhtproxy.jami.net** but can be any DHT node with the REST API enabled. However, if the
+DHT proxy is using push notifications it will depend on another external service (Firebase
+or APN or a Unified Push instance). In this case, only the third one can be self-hosted.
+
+On iOS it is basically not possible to work without push, as the OS from Apple will kill
+any application as soon as it is in background. So you can not disable the usage of push
+notifications. However, for Android, you may want to self-host your proxy (with or without
+unified push support), or you can disable the DHT Proxy and enable "Run in background" in
+order to use your local DHT.
+
+NameServer
+----------
+
+Finally, the last external service you may need is a NameServer. This is used
+to translate addresses (the 40-characters fingerprint ID) to usernames. You may not have access to
+**ns.jami.net**, but you can self-host one (:doc:`/developer/name-server-protocol`) or only use IDs.
\ No newline at end of file
-- 
GitLab