From f77f9bb3c73a22f2e74b7869676365e0d0e07bab Mon Sep 17 00:00:00 2001 From: John Livingston Date: Fri, 11 Jun 2021 18:32:32 +0200 Subject: [PATCH] Documentation. --- README.md | 28 ++++++++++++++++------------ ROADMAP.md | 4 +++- documentation/common.md | 28 ++++++++++++++++------------ documentation/conversejs.md | 35 +++++++++++++++-------------------- documentation/external.md | 19 ++++++++++++------- documentation/prosody.md | 36 ++++++++++++++++++++++++------------ 6 files changed, 86 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index ad67dbc6..69dad570 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,15 @@ # PeerTube plugin livechat -This plugin can provide webchat for peertube videos. +This plugin is meant to provide web chat for peertube videos. -There are multiple way to provide such functionality: +The plugin has to rely on an external tool as web chat backend. There are multiple ways to provide such functionality: -* **builtin prosody:** this plugin can launch a [Prosody](https://prosody.im) process and auto-configure it. [Documentation](documentation/prosody.md). Althought this is still experimental and under development, it is the recommanded setup. -* **builtin converseJS:** you can use an external Jabber/XMPP server with BOSH or Websocket and anonymous loggin enabled. [Documentation](documentation/conversejs.md) -* **external tool:** you can use any external webchat tool, that can be included in an iframe. [Documentation](documentation/external.md) +* **Prosody server controlled by Peertube (recommended):** this plugin can launch a [Prosody](https://prosody.im) process and auto-configure it. [Documentation](documentation/prosody.md). **This is the recommanded setup, and is almost automatic to setup**. +* **Connect to an existing XMPP server with ConverseJS:** you can use an external Jabber/XMPP server. This server has to provide BOSH or Websocket API, accept anonymous loggin, and accept room creation. [Documentation](documentation/conversejs.md) +* **Use an external web chat tool:** you can use any external web chat tool, that can be included in an iframe. [Documentation](documentation/external.md) -For the two first solutions, the connection to the XMPP server is made with [converseJS](https://conversejs.org/). +For the two first solutions, the connection to the XMPP server is made with the [converseJS](https://conversejs.org/) Javascript library. +XMPP is a protocol for chat applications. It is sometime known has Jabber. If you have new feature requests, bugs, or difficulties to setup the plugin, you can use the [Github issue tracker](https://github.com/JohnXLivingston/peertube-plugin-livechat/issues). @@ -22,14 +23,13 @@ If you have any question, or if you want to talk about this plugin, you can join ## Settings +For the chat mode, and related settings, please refer to the corresponding documentation: +* [Prosody server controlled by Peertube (recommended)](documentation/prosody.md). **This is the recommanded setup**. +* [Connect to an existing XMPP server with ConverseJS](documentation/conversejs.md) +* [Use an external web chat tool](documentation/external.md) + There are several common settings. Please see the documentation here: [common settings documentation](documentation/common.md). -Then, please refer to the documentation associated with the mode you are planning to use: - -* **builtin prosody:** this plugin can launch a [Prosody](https://prosody.im) process and auto-configure it. [Documentation](documentation/prosody.md) -* **builtin converseJS:** you can use an external Jabber/XMPP server with BOSH or Websocket and anonymous loggin enabled. [Documentation](documentation/conversejs.md) -* **external tool:** you can use any external webchat tool, that can be included in an iframe. [Documentation](documentation/external.md) - ## Credits Thanks to David Revoy for his work on Peertube's mascot, [Sepia](https://www.davidrevoy.com/index.php?tag/peertube). @@ -37,3 +37,7 @@ Thanks to David Revoy for his work on Peertube's mascot, [Sepia](https://www.dav Some material icons downloaded from this website where used for icons: [Material.io](https://material.io/resources/icons) Some Prosody Modules in the `prosody-modules` folder are under MIT license. Please refer to README files in each subfolder, and to the [COPYING](./prosody-modules/COPYING) file. For more informations, here is [the official Prosody Modules website](https://modules.prosody.im). + +Thanks to [Framasoft](https://framasoft.org) for making [Peertube](https://joinpeertube.org/) possible, and for the support. + +Thanks to [Ritimo](https://www.ritimo.org/) for the financial support. diff --git a/ROADMAP.md b/ROADMAP.md index 30b6e265..6973be3e 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -26,7 +26,9 @@ This roadmap is given as an indication. It will be updated as we go along accord | Done | Component | Feature | Released in version ---|---|---|--- -[ ] | Documentation | Rewrite documentation for more clarity. Add screenshots. Separate user and admin documentation. +[x] | Documentation | Rewrite documentation for more clarity. +[ ] | Documentation | Add screenshots. +[ ] | Documentation | User documentation. [ ] | Builtin Prosody | Room administration: add a button in the plugin settings to open a modal with existing rooms list. [ ] | Builtin Prosody | Check with yunohost how to integrate. [ ] | Settings | Translate settings page. diff --git a/documentation/common.md b/documentation/common.md index f762e181..78fd23d0 100644 --- a/documentation/common.md +++ b/documentation/common.md @@ -2,39 +2,43 @@ There are several options in the plugin settings page that are common to all installation types. -## Automatically open the chat +## Chat behaviour + +### 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 +### 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. +If your web chat tool can be opened in a full window, you can add a button to do so. -NB: The builtin ConverseJS is compatible with this feature. +If you are using an external web chat tool (see the chat mode «Use an external web chat tool»), maybe it will not work in fullscreen (for example if it needs to access the parent window to get video informations). You can disable this button by unchecking this settings. -## Chats are only available for local videos +### 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 +### Users can activate the chat for their 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. +If checked, all live videos will have a checkbox in their properties for enabling the web chat. +The video owner will be able to activate web chats. -## Activate chat for all non-lives +### Activate chat for all lives + +The chat will be available for all Peertube live videos on your instance. + +### Activate chat for all non-lives The chat will be available for all Peertube video that are not live. -## Activate chat for specific videos +### Activate chat for these 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. diff --git a/documentation/conversejs.md b/documentation/conversejs.md index 099a0f3b..735a146c 100644 --- a/documentation/conversejs.md +++ b/documentation/conversejs.md @@ -1,29 +1,19 @@ -# Use an external XMPP server +# Connect to an existing XMPP server with ConverseJS + +If you have an XMPP server, and don't want to provide a web chat application by yourself, you can use the builtin ConverseJS implementation. + +ConverseJS is an Free and Open Source Javascript library to connect to Jabber/XMPP servers. **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 +### Chat mode -First you have to configure [common settings](./common.md). +Just select «Connect to an existing XMPP server with ConverseJS» as chat mode. -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) +#### XMPP service server (mandatory) The XMPP server. For example: ```peertube.im.your_domain```. @@ -31,14 +21,14 @@ NB: If you have an existing Prosody server, you can use its address if it has an 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) +#### 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 +#### BOSH uri OR Websocket uri You have to provide at least one of these two settings. @@ -49,3 +39,8 @@ 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). + +### Chat behaviour + +These settings are common with other chat modes. +Here is the documentation: [common settings](./common.md). diff --git a/documentation/external.md b/documentation/external.md index ae21f3df..883ccd4d 100644 --- a/documentation/external.md +++ b/documentation/external.md @@ -1,16 +1,16 @@ -# Use an external webchat tool +# Use an external web chat tool -You can use any webchat tool that can be included in an «iframe». +You can use any webchat tool that can be included in an HTML «iframe». -## Common settings +## Settings -First you have to configure [common settings](./common.md). +### Chat mode -Then, left settings related to the [builtin prosody](./prosody.md) and [builtin converseJS](./conversejs.md) blank, and fill following settings according to this page. +Just select «Use an external web chat tool» as chat mode. -## Webchat url +### Webchat url -If you are not using the builtin ConverseJS feature, you can speficy here the url for you chat application. +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. @@ -19,6 +19,11 @@ It is possible to use a single chat for all your videos if you omit this paramet Example: ```https://peertube.im.your_domain?room={{VIDEO_UUID}}``` +### Chat behaviour + +These settings are common with other chat modes. +Here is the documentation: [common settings](./common.md). + ## Tips: install your own XMPP webchat Here are some tips if you want to setup a XMPP server yourself. diff --git a/documentation/prosody.md b/documentation/prosody.md index 01b93021..10dc4656 100644 --- a/documentation/prosody.md +++ b/documentation/prosody.md @@ -1,9 +1,20 @@ -# Builtin Prosody XMPP Server +# Prosody server controlled by Peertube -Althought this mode is still experimental and under heavy development, it is the recommanded setup mode. +This is the recommended setup mode for this plugin. Peertube will launch a [Prosody](https://prosody.im) process, with a custom configuration. +Prosody is a Free and Open Source XMPP/Jabber server software. + +With this mode, the Peertube server will be able to communicate with the Prosody server, with following features: + +- auto login: if a user is logged in on the Peertube instance, it will be automatically authenticated in the web chat +- access rights: Peertube instance's administrators and moderators will automatically be owner for all created chat rooms. +- access rights: the Peertube's user who has added the video will automatically be moderator on the chat room. +- moderation tools will be enabled +- it will not be possible to create a room that is not linked to a video +- chat room will automatically get some informations from the video (title, ...) + ## Prerequisite ### For standard Peertube installations @@ -23,6 +34,8 @@ sudo systemctl disable prosody && sudo systemctl stop prosody And that's it! The Prosody process launched by the plugin will listen on a specific port, and only on the localhost interface. +You don't to open any external port on your firewall. +The default local port will be 52800 and can be changed in the plugin settings. ### For Docker installations @@ -35,24 +48,23 @@ You can find the source for this Dockerfile [here](../docker/Dockerfile.buster). ## Settings -### Common settings +### Chat mode -First you have to configure [common settings](./common.md). +Just select «Prosody server controlled by Peertube» as chat mode. -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 +#### 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. +### Chat behaviour + +These settings are common with other chat modes. +Here is the documentation: [common settings](./common.md). + ## Notes All instance moderators and admins will be owner for created chat rooms. If the video is local (not from a remote Peertube), the video owner will be admin in the chat room. You can use [ConverseJS moderation commands](https://conversejs.org/docs/html/features.html#moderating-chatrooms) to moderate the room. -When you open the chat room in full screen, there will also be a menu with dedicated commands in the top right. +When you open the chat room in full screen, there will also be a menu with dedicated commands on the top right.