~emersion/public-inbox

This thread contains a patchset. You're looking at the original emails, but you may wish to use the patch review UI. Review patch
1

[PATCH gamja v2] doc: how to connect with a local soju instance

Details
Message ID
<20210607131805.3244588-1-porcellis@eletrotupi.com>
DKIM signature
pass
Download raw message
Patch: +21 -8
h9xNysPQqGNE-N_8=@emersion.fr>
References: <9Ext-xSl_QhEyVU-YsQSMeTy03vNvNkJBEAsU2ip7dSwNcdR1HPiioqSYp4AoBVBCKhyc-8f0AoG_sIqaCn0EOQdSN4
h9xNysPQqGNE-N_8=@emersion.fr>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit

---

I've merged the soju sections into a single paragraph. One thing to
notice, is that I don't really know if when running soju in a production
environment, you'll not need to set the `http-origin` directive. I wrote
it like that, as you haven't specified that before and I've only
encountered this problem when running locally. Let me know if it need
any adjustments.

 README.md | 29 +++++++++++++++++++++--------
 1 file changed, 21 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 7100e46..80f9d7f 100644
--- a/README.md
+++ b/README.md
@@ -12,12 +12,6 @@ First install dependencies:

    npm install --production

### [soju]

Add a WebSocket listener to soju, e.g. `listen wss://127.0.0.1:8080`.

Configure your reverse proxy to serve gamja files and proxy `/socket` to soju.

### [webircgateway]

Setup webircgateway to serve gamja files:
@@ -59,8 +53,27 @@ Start your IRC WebSocket server, e.g. on port 8080. Then run:
    npm install
    npm start

This will start a development HTTP server for gamja. Connect to it and append
`?server=ws://localhost:8080` to the URL.
This will start a development HTTP server for gamja. You can proceed to connect
normally (filling the form), messing with the `config.json` file on gamja's
source code root or overriding the settings via query parameters on the URL.

## [soju]

In order to use with soju, there's two soju's directives you'll need to
configure, the `listen` directive to make it listen for a incoming WebSocket
connection and the `http-origin` to allow it to receive connections from your
gamja setup.

In a production environment, you'll likely have soju and gamja running on the
same server, and therefore you can just setup your reverse proxy to serve gamja
files while proxying `/socket` to soju. This will remove the need to set
`http-origin`, and all you'll need is to set soju to listen for a secure
WebSocket connection: `listen wss://127.0.0.1:8000`.

In a development environment, you'll need to allow soju to receive connections
from gamja over a Insecure WebSocket, e.g. `listen
ws+insecure://127.0.0.1:8000` and configure the `http-origin` to the same host
and port.

## Query parameters

-- 
2.31.1
Details
Message ID
<M8tfn405OfU0U23cdqit5gqlrBpq_AY_vrOjxA4oHRy55tVpEOO69QFbDoaxb1ngjD7L16uoGNh_6mgftMe7llhsgpm-_KF1FYQlqEa7ERI=@emersion.fr>
In-Reply-To
<20210607131805.3244588-1-porcellis@eletrotupi.com> (view parent)
DKIM signature
pass
Download raw message
> I've merged the soju sections into a single paragraph. One thing to
> notice, is that I don't really know if when running soju in a production
> environment, you'll not need to set the `http-origin` directive. I wrote
> it like that, as you haven't specified that before and I've only
> encountered this problem when running locally. Let me know if it need
> any adjustments.

You shouldn't need to. I've tried to make this clearer in [1].

[1]: https://git.sr.ht/~emersion/soju/commit/520ed76adf33cc516964938d2625660b3a6147a5

>  README.md | 29 +++++++++++++++++++++--------
>  1 file changed, 21 insertions(+), 8 deletions(-)
>
> diff --git a/README.md b/README.md
> index 7100e46..80f9d7f 100644
> --- a/README.md
> +++ b/README.md
> @@ -12,12 +12,6 @@ First install dependencies:
>
>      npm install --production
>
> -### [soju]
> -
> -Add a WebSocket listener to soju, e.g. `listen wss://127.0.0.1:8080`.
> -
> -Configure your reverse proxy to serve gamja files and proxy `/socket` to soju.
> -
>  ### [webircgateway]
>
>  Setup webircgateway to serve gamja files:
> @@ -59,8 +53,27 @@ Start your IRC WebSocket server, e.g. on port 8080. Then run:
>      npm install
>      npm start
>
> -This will start a development HTTP server for gamja. Connect to it and append
> -`?server=ws://localhost:8080` to the URL.
> +This will start a development HTTP server for gamja. You can proceed to connect
> +normally (filling the form), messing with the `config.json` file on gamja's
> +source code root or overriding the settings via query parameters on the URL.

I'd prefer to keep an explicit mention of what to do for a WebSocket server
running on localhost:8080. This makes it easier for users to figure out what
exact parameter to set.

> +## [soju]

This is no longer a sub-section of the "Usage" section. It should remain so.

Why move it down?

> +In order to use with soju, there's two soju's directives you'll need to
> +configure, the `listen` directive to make it listen for a incoming WebSocket
> +connection and the `http-origin` to allow it to receive connections from your
> +gamja setup.

As per the above, http-origin is only necessary in development env. Let's only
mention it in the development paragraph.

> +In a production environment, you'll likely have soju and gamja running on the
> +same server, and therefore you can just setup your reverse proxy to serve gamja
> +files while proxying `/socket` to soju. This will remove the need to set
> +`http-origin`, and all you'll need is to set soju to listen for a secure
> +WebSocket connection: `listen wss://127.0.0.1:8000`.

When using a reverse proxy, should probably just listen with ws+insecure? I
guess HTTPS works too, but is a bit unnecessary if the only client will be a
reverse proxy.

The rest of the examples use :8080 for the example port, not :8000.

> +In a development environment, you'll need to allow soju to receive connections
> +from gamja over a Insecure WebSocket, e.g. `listen
> +ws+insecure://127.0.0.1:8000` and configure the `http-origin` to the same host
> +and port.

I think this is the exact incantation:

    listen ws+insecure://127.0.0.1:8080
    http-origin 127.0.0.1:8081
Reply to thread Export thread (mbox)