Documentation.

documentation/common.md

@@ -0,0 +1,43 @@
+# Common settings documentation
+
+There are several options in the plugin settings page that are common to all installation types.
+
+## Automatically open the chat
+
+If checked, the chat will be loaded as soon as you are on the video page.
+
+## Show the «open in new window» button
+
+If your webchat can be opened in a full window, you can add a button to do so.
+
+NB: The builtin ConverseJS is compatible with this feature.
+
+## Chats are only available for local videos
+
+Peertube is a federated service. Plugins are only available on the server you are browsing.
+So, if you are watching a remote video, only you will have the webchat, not users from remote instances.
+Therefore, this options is checked by default and prevent displaying a webchat for remote videos.
+
+## Activate chat for all lives
+
+The chat will be available for all Peertube Live on your instance.
+This is the main purpose of this plugin: providing a chatting experience to user watching a live video.
+
+## Activate chat for all non-lives
+
+The chat will be available for all Peertube video that are not live.
+
+## Activate chat for specific videos
+
+You can choose some UUIDs for which the chat will be available.
+If you don't want te enable the feature for all videos, you can use this field to list videos UUIDs.
+You can add comments: everything rights to the # character will be stripped off, as for empty lines.
+
+NB: this feature will probably soon disappear. I planned to add a checkbox in each video settings.
+
+### Webchat iframe style attribute
+
+You can add some custom styles that will be added to the iframe.
+For example a custom width:
+
+```width:400px;```

documentation/conversejs.md

@@ -0,0 +1,51 @@
+# Use an external XMPP server
+
+**Important Note**: If you don't have a running XMPP server, here is a
+**[tutorial to install Prosody XMPP Server](./tutorials/prosody.md) on your Peertube instance**.
+
+## Plugin Settings
+
+### Common settings
+
+First you have to configure [common settings](./common.md).
+
+Then, left settings related to the [builtin prosody](./prosody.md) blank, and fill following settings according to this page.
+
+### Use builtin ConverseJS
+
+Check this checkbox to use this mode.
+
+If you have an XMPP server, and don't want to provide a webchat application by yourself, you can use the builtin ConverseJS implementation.
+
+If you don't have a running XMPP server, you can use
+[this tutorial](./tutorials/prosody.md) to setup Prosody Server
+on your Peertube's instance.
+
+You have to fill the following parameters:
+
+#### Builtin webchat: XMPP service server (mandatory)
+
+The XMPP server. For example: ```peertube.im.your_domain```.
+
+NB: If you have an existing Prosody server, you can use its address if it has anonymous authentication on.
+Otherwise, you can create a subdomain (see [the example file](documentation/examples/prosody/virtualhost.cfg.lua)).
+The ```peertube.im``` is part of the example, you have to replace the entire value.
+
+#### Builtin webchat: XMPP room template (mandatory)
+
+The room to join on your XMPP server.
+You can have a single room for all webchats, or you can use the placeholder ```{{{VIDEO_UUID}}}``` to insert the video UUID and have a custom room for each video.
+
+Example: ```room_{{VIDEO_UUID}}@room.peertube.im.your_domain```
+
+#### Builtin webchat: BOSH uri OR Builtin webchat: WS uri
+
+You have to provide at least one of these two settings.
+
+Example for BOSH: ```https://peertube.im.yiny.org/http-bind```
+
+Example for Websocket: ```wss://peertube.im.yiny.org/xmpp-websocket```
+
+NB: ConverseJS can also use the ```/.well-known/host-meta``` file to discover services.
+See ConverseJS [documentation](https://conversejs.org/docs/html/configuration.html#discover-connection-methods)
+and XMPP [documentation](https://xmpp.org/extensions/xep-0156.html#httpexamples).

documentation/external.md

@@ -0,0 +1,67 @@
+# Use an external webchat tool
+
+You can use any webchat tool that can be included in an «iframe».
+
+## Common settings
+
+First you have to configure [common settings](./common.md).
+
+Then, left settings related to the [builtin prosody](./prosody.md) and [builtin converseJS](./conversejs.md) blank, and fill following settings according to this page.
+
+## Webchat url
+
+If you are not using the builtin ConverseJS feature, you can speficy here the url for you chat application.
+
+You can add the string {{VIDEO_UUID}} in the url, it will be replaced by the video UUID.
+
+It is possible to use a single chat for all your videos if you omit this parameter.
+
+Example:
+```https://peertube.im.your_domain?room={{VIDEO_UUID}}```
+
+## Tips: install your own XMPP webchat
+
+Here are some tips if you want to setup a XMPP server yourself.
+
+### Custom ConverseJS webchat
+
+If you want to setup your own webchat with converseJS on a different webserver, here is some tips.
+
+Once you have a XMPP server that allow anonymous authentication, with bosh
+(or websocket) enabled, you can - for example - setup a html page that looks like
+[this one](./examples/converseJS/index.html). You have of course to
+replace the path /conversejs/dist with your converseJS path, and replace peertube.im.your_domain
+by your actual domain.
+
+NB: converseJS has an option «discover_connection_methods» to find your server configuration (bosh, websocket, ...).
+To use it, you have to add a file [/.well-known/host-meta](./examples/converseJS/host-meta).
+Please refer to the converseJS documentation.
+
+### XMPP Server: Prosody
+
+You can use Prosody for the XMPP backend.
+
+You can find an example configuration file [here](./examples/prosody/virtualhost.cfg.lua) or use [this tutorial](./tutorials/prosody.md)
+to setup Prosody from scratch.
+
+Replace admin@your_xmpp_provider_domain with Jabber ids of users that you want to be admin for your server and public chatrooms.
+This users have to be on another domain/virtualhost (which don't use anonymous authentication).
+It can even be on another XMPP server. Or you can add a virtualhost on the
+Peertube server's prosody config.
+If you have no XMPP account, remove the line (but you will not be able to moderate rooms).
+
+Please refer to the [Prosody documentation](https://prosody.im/doc/) and to [the tutorial](./tutorials/prosody.md) for other modifications
+(how to get the ssl certificates, ...).
+
+NB : if you have not nginx on your server, please replace by the correct parameter.
+
+### XMPP over HTTP: nginx
+
+You can use the reverse proxy nginx to server the Prosody Bosh server.
+So your requests will be on the 443 port, and it will minimise cross domains constraints.
+
+There is an example file [here](./examples/nginx/site.conf).
+
+NB: this example files also serve the static html files with converseJS.
+
+NB: it is recommanded to change ```Access-Control-Allow-Origin``` to something else that ```"*"``` (your peertubes uri).

documentation/prosody.md

@@ -0,0 +1,46 @@
+# Builtin Prosody XMPP Server
+
+Althought this mode is still experimental and under heavy development, it is the recommanded setup mode.
+
+Peertube will launch a [Prosody](https://prosody.im) process, with a custom configuration.
+
+## For Docker installations
+
+This mode is not yet compatible with a Docker Peertube installation.
+If you are using Docker and want to help to make this work, please contact me.
+
+## Prerequisite
+
+You have to install [Prosody](https://prosody.im) on your server:
+
+```bash
+sudo apt-get install prosody
+```
+
+If you are not using prosody for anything else on your server, you can then disabled it:
+
+```bash
+sudo systemctl disable prosody && sudo systemctl stop prosody
+```
+
+**NB:** the plugin will create a directory in the `/tmp/` folder. Please ensure that the `peertube` user has write access to this directory.
+
+And that's it!
+
+The Prosody process launched by the plugin will listen on a specific port, and only on the localhost interface.
+
+## Settings
+
+### Common settings
+
+First you have to configure [common settings](./common.md).
+
+Then, left settings related to the [builtin converseJS](./converseJS.md) blank, and fill following settings according to this page.
+
+### Use the builtin Prosody XMPP Server
+
+Check this checkbox to activate this mode.
+
+#### Builtin prosody: Prosody port
+
+This is the port that the Prosody server will use. By default it is set to 52800. If you want to use another port, just change the value here.