XMPP connections documentation (#114)

languages/settings/en.yml

@@ -170,11 +170,11 @@ prosody_s2s_interfaces_description: |
     <li>172.18.0.42</li>
   </ul>
 
-prosody_certificates_dir_label: "Certificates directory"
+prosody_certificates_dir_label: "Certificates folder"
 prosody_certificates_dir_description: |
   If this field is empty, the plugin will generate and use self-signed certificates.<br>
   If you want to use other certificates, just specify here the folder where
-  Prosody can find them. Note: the "peertube" user must have read access to this directory.
+  Prosody can find them. Note: the "peertube" user must have read access to this folder.
 
 prosody_c2s_label: "Enable client to server connections"
 prosody_c2s_description: |

support/documentation/content/documentation/admin/advanced/xmpp_clients.en.md

@@ -1,15 +1,99 @@
 +++
 title="XMPP clients"
-description="Allow connections using external XMPP accounts and XMPP clients"
+description="Allow connections using XMPP clients"
 weight=30
 chapter=false
 +++
 
-{{% notice warning %}}
+This chat module is based on the XMPP protocol, also known as Jabber.
-This page is not written yet. It should explain how you can connect with XMPP clients.
+It is therefore possible to connect to the chats using [XMPP client software](https://en.wikipedia.org/wiki/XMPP#Clients).
+This can for example be useful to facilitate moderation operations.
+
+For the user documentation associated with these features, please refer to the [user documentation page](/peertube-plugin-livechat/documentation/user/xmpp_clients/).
+
+{{% notice info %}}
+Enabling these features requires configuration changes on the server, and
+on the DNS records. It is not possible to configure this only from the
+Peertube interface, and it requires some basic system some basic system
+admin skills.
 {{% /notice %}}
 
-{{% notice tip %}}
+## Login to your Peertube account
-For now you can't connect to your Peertube chat account using a XMPP client.
+
-This feature could be added one day, depending on the interest about it.
+{{% notice warning %}}
+This feature is not yet available, and will come in a future version of the plugin.
 {{% /notice %}}
+
+## Connection using an external XMPP account
+
+To enable this feature, you will need to set up your server and DNS
+records, so that XMPP clients can find and access the
+[Prosody server](https://prosody.im) that this plugin uses internally.
+
+### Plugin settings
+
+Start by going to the livechat plugin settings of your instance, then
+enable the setting "Enable connection to room using external XMPP accounts".
+By checking this settings, new settings appear below.
+
+First of all, the "Prosody server to server port" field.
+This one defaults to 5269, which is the standard port for this service.
+You can however change to another port, if this is already in use on your server.
+
+Next, the field "Server to server network interfaces" field allows you to specify
+which network interfaces the server should listen on.
+The default value "*, ::" indicates to listen on all IP addresses.
+You can change these values, if you wish to listen on only certain IP addresses.
+The syntax is explained next to the setting.
+
+For the "Certificate folder" setting, you can leave it empty.
+In this case, the plugin will automatically generate self-signed certificates.
+Some XMPP servers may refuse to connect, depending on their configuration.
+In this case, you can indicate here a path on the server, in which you 
+must place certificates to be used by the module.
+It is up to you to generate and renew them.
+You can refer to the [Prosody documentation](https://prosody.im/doc/certificates).
+
+{{% notice tip %}}
+If you want to use the ProsodyCtl utility to import
+certificates, this utility is available (once Peertube is started) using
+the following command (adapting the path to your Peertube data folder,
+and replacing "xxx" with the arguments you wish to pass to
+prosodyctl):
+`sudo -u peertube /var/www/peertube/storage/plugins/data/peertube-plugin-livechat/prosodyAppImage/squashfs-root/AppRun prosodyctl xxx`
+{{% /notice %}}
+
+### Firewall
+
+You must open the configured port (5269 by default) on your firewall.
+
+If you are using Docker for your Peertube, you need to modify the
+`docker-compose.yml` file to open port 5269 of the `peertube` container,
+so that the outer world can connect to it.
+
+### DNS
+
+You need to add a [DNS record](https://prosody.im/doc/dns) allowing
+remote servers to find the "room.your_instance.tld" component.
+
+The easiest way to do this is to add an SRV record for the "room"
+[subdomain](https://prosody.im/doc/dns#subdomains):
+
+* record name: _xmpp-server._tcp.room.your_instance.tld. (replace «your_instance.tld» by your instance uri)
+* TTL: 3600
+* class: IN
+* SRV: 0
+* priority: 0
+* weight: 5
+* port: 5269 (adapt if your changed the default port)
+* target: your_instance.tld. (replace by your instance uri)
+
+Be careful to keep the dot after "your_instance.tld".
+
+Using the `dig` command to check your record,
+you should get a result similar to this:
+
+```bash
+$ dig +short _xmpp-server._tcp.room.videos.john-livingston.fr. SRV
+0 5 5269 videos.john-livingston.fr.
+```

support/documentation/content/documentation/admin/advanced/xmpp_clients.fr.md

@@ -1,10 +1,104 @@
 +++
-title="Allow connection using XMPP clients"
+title="Clients XMPP"
-description="Allow connections using external XMPP accounts and XMPP clients"
+description="Autoriser la connexion en utilisant des clients XMPP."
 weight=30
 chapter=false
 +++
 
-{{% notice warning %}}
+Ce module de tchat repose sur le protocole XMPP, aussi connu sous le nom de Jabber.
-This page is not yet translated in your language, please refer to the english version. You can switch to it by using the language selector in the left menu.
+Il est donc possible de se connecter aux tchats en utilisant des
+[logiciels clients XMPP](https://fr.wikipedia.org/wiki/Clients_XMPP).
+Cela peut par exemple être utile pour faciliter les opérations de modération.
+
+Pour la documentation utilisateur⋅rice associé à ces fonctionnalités, veuillez
+vous référer à la page [de documentation utilisateur⋅rice](/peertube-plugin-livechat/fr/documentation/user/xmpp_clients/).
+
+{{% notice info %}}
+L'activation de ces fonctionnalités demande des changements de configuration
+sur le serveur, et sur les enregistrements DNS. Il n'est pas possible de les
+activer uniquement depuis l'interface de Peertube, et cela demande d'avoir
+quelques compétences basiques d'admin système.
 {{% /notice %}}
+
+## Connexion à votre compte Peertube
+
+{{% notice warning %}}
+Cette fonctionnalité n'est pas encore disponible, et viendra dans une
+prochaine version du plugin.
+{{% /notice %}}
+
+## Connexion en utilisant un compte XMPP externe
+
+Pour activer cette fonctionnalité, il va falloir paraméter votre serveur et vos
+enregistrements DNS, de sorte que les clients XMPP puissent trouver et accéder
+au serveur [Prosody](https://prosody.im) que ce plugin utilise en interne.
+
+### Paramètres du plugin
+
+Commencez par aller dans les paramètres du plugin livechat de votre instance,
+puis activez le paramètre «Autoriser les connexions aux salons via des comptes XMPP externes».
+En cochant celui-ci, de nouveaux champs apparaissent en dessous.
+
+Tout d'abord, le champs «Port Prosody serveur vers serveur». Celui-ci prend par
+défaut la valeur 5269, qui est le port standard pour ce service.
+Vous pouvez toutefois changer pour un autre port, si celui-ci est déjà utilisé
+sur votre serveur.
+
+Ensuite, le champs «Interfaces réseau pour les connexions serveur vers serveur»
+vous permet d'indiquer sur quelles interfaces réseau le serveur doit écouter.
+La valeur par défaut «*, ::» indique d'écouter sur toutes les addresses IP.
+Vous pouvez changer ces valeurs, si vous souhaiter n'écouter que sur certaines
+IP. La syntaxe est expliquée à coté du champs.
+
+Pour le champs «Dossiers des certificats», vous pouvez le laisser vide.
+Dans ce cas là, le plugin va générer automatiquement des certificats auto-signés.
+Il se pourrait que certains serveurs XMPP refusent de se connecter, cela dépendant
+de leur paramétrage.
+Dans ce cas, vous pouvez indiquer ici un chemin sur le serveur, dans lequel vous
+placerez des certificats à utiliser par le module.
+Charge à vous de les générer et de les renouveller.
+Vous pouvez vous référer à la documentation de [Prosody](https://prosody.im/doc/certificates).
+
+{{% notice tip %}}
+Si vous voulez utiliser l'utilitaire ProsodyCtl pour importer des certificats
+letsencrypts, cet utilitaire est disponible (une fois Peertube démarré) en utilisant
+la commande qui suit (en adaptant le chemin vers votre dossier data Peertube,
+et en remplaçant «xxx» par les arguments que vous souhaitez passer à
+prosodyctl):
+`sudo -u peertube /var/www/peertube/storage/plugins/data/peertube-plugin-livechat/prosodyAppImage/squashfs-root/AppRun prosodyctl xxx`
+{{% /notice %}}
+
+### Pare-feu
+
+Vous devez ouvrir le port configuré (5269 par défaut) sur votre pare-feu.
+
+Si vous utilisez Docker pour votre Peertube, il faut modifier le fichier
+`docker-compose.yml` pour ouvrir le port 5269 du conteneur `peertube` au
+monde extérieur.
+
+### DNS
+
+Vous devez ajouter un [enregistrement DNS](https://prosody.im/doc/dns) permettant
+aux serveurs distant de trouver le composant «room.votre_instance.tld».
+
+Le plus simple pour cela est d'ajouter un enregistrement SRV pour le
+[sous-domaine](https://prosody.im/doc/dns#subdomains) «room»:
+
+* nom de l'enregistrement: _xmpp-server._tcp.room.votre_instance.tld. (remplacez «votre_instance.tld» par la valeur adéquate)
+* TTL: 3600
+* class: IN
+* SRV: 0
+* priority: 0
+* weight: 5
+* port: 5269 (adaptez si vous avez changé le port)
+* target: votre_instance.tld. (remplacez par la valeur adéquate)
+
+Attention à bien conserver le point après «votre_instance.tld».
+
+En utilisant la commande `dig` pour vérifier votre enregistrement,
+vous devriez obtenir un résultat similaire à celui-ci:
+
+```bash
+$ dig +short _xmpp-server._tcp.room.videos.john-livingston.fr. SRV
+0 5 5269 videos.john-livingston.fr.
+```

support/documentation/content/documentation/user/xmpp_clients.fr.md

@@ -16,14 +16,14 @@ les administrateur⋅rices de votre instance Peertube. Il se peut donc que vous
 n'y ayez pas accès.
 {{% /notice %}}
 
-## Connection à votre compte Peertube
+## Connexion à votre compte Peertube
 
 {{% notice warning %}}
 Cette fonctionnalité n'est pas encore disponible, et viendra dans une
 prochaine version du plugin.
 {{% /notice %}}
 
-## Connection en utilisant un compte XMPP externe
+## Connexion en utilisant un compte XMPP externe
 
 Si cette fonctionnalité est activée sur votre instance, vous pouvez vous
 connecter aux tchats Peertube en utilisant un compte XMPP quelconque.