diff --git a/CHANGELOG.md b/CHANGELOG.md index 8507bcbf..d2dbc895 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## ??? +## v2.0.0 * Code is now in Typescript * Builtin Prosody server, for easy configuration diff --git a/README.md b/README.md index da222019..bcb87373 100644 --- a/README.md +++ b/README.md @@ -2,16 +2,13 @@ This plugin can provide webchat for peertube videos. -Warning: the webchat is not provided by this plugin. You have to rely on an external tool. There are multiple way to provide such functionality: -* by having a Jabber/XMPP server with BOSH or Websocket and anonymous loggin -* by having an external webchat tool, that will be included in an iframe +* **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) -For the first solution, the connection to the XMPP server is made with [converseJS](https://conversejs.org/). - -**Important Note**: If you don't have a running XMPP server, here is a -**[tutorial to install Prosody XMPP Server](documentation/tutorials/prosody.md) on your Peertube instance**. This is the simpliest way to make this plugin work. +For the two first solutions, the connection to the XMPP server is made with [converseJS](https://conversejs.org/). 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). @@ -23,145 +20,13 @@ If you have any question, or if you want to talk about this plugin, you can join ## Settings -There are several options in the plugin settings page. +There are several common settings. Please see the documentation here: [common settings documentation](documentation/common.md). -### Automatically open the chat +Then, please refer to the documentation associated with the mode you are planning to use: -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. - -### Use builtin ConverseJS - -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](documentation/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). - -### 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}}``` - -### Webchat iframe style attribute - -You can add some custom styles that will be added to the iframe. -For example a custom width: - -```width:400px;``` - -## XMPP backend with ConverseJS - -### ConverseJS - -You can use the builtin ConverseJS implementation. - -#### 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](documentation/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](documentation/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](documentation/examples/prosody/virtualhost.cfg.lua) or use [this tutorial](documentation/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](documentation/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](documentation/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). +* **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 diff --git a/documentation/common.md b/documentation/common.md new file mode 100644 index 00000000..f762e181 --- /dev/null +++ b/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;``` diff --git a/documentation/conversejs.md b/documentation/conversejs.md new file mode 100644 index 00000000..099a0f3b --- /dev/null +++ b/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). diff --git a/documentation/external.md b/documentation/external.md new file mode 100644 index 00000000..ae21f3df --- /dev/null +++ b/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). diff --git a/documentation/prosody.md b/documentation/prosody.md new file mode 100644 index 00000000..43fe1aa1 --- /dev/null +++ b/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. diff --git a/server/lib/settings.ts b/server/lib/settings.ts index e2b29970..cfeefb45 100644 --- a/server/lib/settings.ts +++ b/server/lib/settings.ts @@ -10,17 +10,47 @@ export function initSettings (options: RegisterServerOptions): void { type: 'input-checkbox', default: false, private: false, // not private so that I can check when doing support - descriptionHTML: 'Please read the ' + - 'documentation ' + - 'before trying to use this plugin.
' + - 'There is 3 way to use it:
' + - 'Before asking for help, please use this diagnostic tool: ' + - 'Launch diagnostic.
' + descriptionHTML: ` +Please read the + + documentation + +before trying to use this plugin.
+There is 3 way to use it: + +
+Before asking for help, please use this diagnostic tool: +Launch diagnostic +
` }) registerSetting({ name: 'chat-auto-display',