matty/peertube-plugin-livechat
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation.

Browse Source
This commit is contained in:
John Livingston 2021-04-16 17:55:48 +02:00
parent 0b40a8ff9a
commit 8ddbb21c7f
7 changed files with 258 additions and 156 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

@ -1,6 +1,6 @@
# Changelog # Changelog
## ??? ## v2.0.0
* Code is now in Typescript * Code is now in Typescript
* Builtin Prosody server, for easy configuration * Builtin Prosody server, for easy configuration

153
README.md
View File

@ -2,16 +2,13 @@
This plugin can provide webchat for peertube videos. 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: There are multiple way to provide such functionality:
* by having a Jabber/XMPP server with BOSH or Websocket and anonymous loggin * **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.
* by having an external webchat tool, that will be included in an iframe * **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/). For the two first solutions, 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.
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). 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 ## 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. * **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)
### Show the «open in new window» button * **external tool:** you can use any external webchat tool, that can be included in an iframe. [Documentation](documentation/external.md)
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).
## Credits ## Credits

43
documentation/common.md Normal file
View File

@ -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;```

51
documentation/conversejs.md Normal file
View File

@ -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).

67
documentation/external.md Normal file
View File

@ -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).

46
documentation/prosody.md Normal file
View File

@ -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.

52
server/lib/settings.ts
View File

@ -10,17 +10,47 @@ export function initSettings (options: RegisterServerOptions): void {
type: 'input-checkbox', type: 'input-checkbox',
default: false, default: false,
private: false, // not private so that I can check when doing support private: false, // not private so that I can check when doing support
descriptionHTML: 'Please read the ' + descriptionHTML: `
'<a href="https://github.com/JohnXLivingston/peertube-plugin-livechat" target="_blank">documentation<a> ' + Please read the
'before trying to use this plugin.<br>' + <a href="https://github.com/JohnXLivingston/peertube-plugin-livechat/blob/main/README.md" target="_blank">
'There is 3 way to use it: <ul>' + documentation
'<li>By installing the Prosoxy XMPP server package on your server, ' + </a>
'and using the «builtin Prosody XMPP Server» feature.</li>' + before trying to use this plugin.<br>
'<li>By using an existing XMPP server, with anonymous authentication and rooms enabled.</li>' + There is 3 way to use it:
'<li>By using any external webchat that can be included in an iframe.</li>' + <ul>
'</ul><br>' + <li>
'Before asking for help, please use this diagnostic tool: ' + By installing the Prosoxy XMPP server package on your server,
'<a href="' + getBaseRouter() + 'settings/diagnostic" target="_blank">Launch diagnostic</a>.<br>' and using the «builtin Prosody XMPP Server» feature.
<a
href="https://github.com/JohnXLivingston/peertube-plugin-livechat/blob/main/documentation/prosody.md"
target="_blank"
>
See Documentation
</a>
</li>
<li>
By using an existing XMPP server, with anonymous authentication and rooms enabled.
<a
href="https://github.com/JohnXLivingston/peertube-plugin-livechat/blob/main/documentation/conversejs.md"
target="_blank"
>
See Documentation
</a>
</li>
<li>
By using any external webchat that can be included in an iframe.
<a
href="https://github.com/JohnXLivingston/peertube-plugin-livechat/blob/main/documentation/external.md"
target="_blank"
>
See Documentation
</a>
</li>
</ul>
<br>
Before asking for help, please use this diagnostic tool:
<a href="${getBaseRouter()}settings/diagnostic" target="_blank">Launch diagnostic</a>
<br>`
}) })
registerSetting({ registerSetting({
name: 'chat-auto-display', name: 'chat-auto-display',