diff --git a/README.md b/README.md index 63b9ba1..1e71e17 100644 --- a/README.md +++ b/README.md @@ -12,52 +12,7 @@ First install dependencies: npm install --production -Then configure an HTTP server to serve the gamja files. Below are some -server-specific instructions. - -### [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: - -```ini -[fileserving] -enabled = true -webroot = /path/to/gamja -``` - -Then connect to webircgateway and append `?server=/webirc/websocket/` to the -URL. - -### nginx - -If you use nginx as a reverse HTTP proxy, make sure to bump the default read -timeout to a value higher than the IRC server PING interval. Example: - -``` -location / { - root /path/to/gamja; -} - -location /socket { - proxy_pass http://127.0.0.1:8080; - proxy_read_timeout 600s; - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "Upgrade"; - proxy_set_header X-Forwarded-For $remote_addr; - proxy_set_header X-Forwarded-Proto $scheme; -} -``` - -If you are unable to configure the proxy timeout accordingly, or if your IRC -server doesn't send PINGs, you can set the `server.ping` option in -`config.json` (see below). +Then [configure an HTTP server] to serve the gamja files. ### Development server @@ -76,63 +31,9 @@ Optionally, [Parcel] can be used to build a minified version of gamja. npm install --include=dev npm run build -## Query parameters +## Configuration -gamja settings can be overridden using URL query parameters: - -- `server`: path or URL to the WebSocket server -- `nick`: nickname -- `channels`: comma-separated list of channels to join (`#` needs to be escaped) -- `open`: [IRC URL] to open -- `debug`: if set to 1, debug mode is enabled - -Alternatively, the channels can be set with the URL fragment (ie, by just -appending the channel name to the gamja URL). - -## Configuration file - -gamja default settings can be set using a `config.json` file at the root: - -```js -{ - // IRC server settings. - "server": { - // WebSocket URL or path to connect to (string). Defaults to "/socket". - "url": "wss://irc.example.org", - // Channel(s) to auto-join (string or array of strings). - "autojoin": "#gamja", - // Controls how the password UI is presented to the user. Set to - // "mandatory" to require a password, "optional" to accept one but not - // require it, "disabled" to never ask for a password, "external" to - // use SASL EXTERNAL, "oauth2" to use SASL OAUTHBEARER. Defaults to - // "optional". - "auth": "optional", - // Default nickname (string). If it contains a "*" character, it will - // be replaced with a random string. - "nick": "asdf", - // Don't display the login UI, immediately connect to the server - // (boolean). - "autoconnect": true, - // Interval in seconds to send PING commands (number). Set to 0 to - // disable. Enabling PINGs can have an impact on client power usage and - // should only be enabled if necessary. - "ping": 60 - }, - // OAuth 2.0 settings. - "oauth2": { - // OAuth 2.0 server URL (string). The server must support OAuth 2.0 - // Authorization Server Metadata (RFC 8414) or OpenID Connect - // Discovery. - "url": "https://auth.example.org", - // OAuth 2.0 client ID (string). - "client_id": "asdf", - // OAuth 2.0 client secret (string). - "client_secret": "ghjk", - // OAuth 2.0 scope (string). - "scope": "profile" - } -} -``` +gamja can be configured via a [configuration file] and via [URL parameters]. ## Contributing @@ -146,10 +47,10 @@ AGPLv3, see LICENSE. Copyright (C) 2020 The gamja Contributors [gamja]: https://sr.ht/~emersion/gamja/ -[soju]: https://soju.im -[webircgateway]: https://github.com/kiwiirc/webircgateway [mailing list]: https://lists.sr.ht/~emersion/public-inbox [issue tracker]: https://todo.sr.ht/~emersion/gamja [Parcel]: https://parceljs.org -[IRC URL]: https://datatracker.ietf.org/doc/html/draft-butcher-irc-url-04 +[configure an HTTP server]: doc/setup.md +[configuration file]: doc/config-file.md +[URL parameters]: doc/url-params.md [#soju on Libera Chat]: ircs://irc.libera.chat/#soju diff --git a/doc/config-file.md b/doc/config-file.md new file mode 100644 index 0000000..ea06557 --- /dev/null +++ b/doc/config-file.md @@ -0,0 +1,45 @@ +# Configuration file + +gamja can be configured using a `config.json` file at the root. Example: + +```json +{ + "server": { + "url": "wss://irc.example.org", + "autojoin": "#gamja" + }, + "oauth2": { + "url": "https://auth.example.org", + "client_id": "asdf" + } +} +``` + +## IRC server + +The `server` object configures the IRC server. + +- `url` (string): WebSocket URL or path to connect to. Defaults to `/socket`. +- `autojoin` (string or array of strings): Channel(s) to automatically join + after connecting. +- `auth` (string): configure how the password UI is presented to the user. Set + to `mandatory` to require a password, `optional` to accept one but not + require it, `disabled` to never ask for a password, `external` to use SASL + EXTERNAL, `oauth2` to use SASL OAUTHBEARER. Defaults to `optional`. +- `nick` (string): default nickname. If it contains a `*` character, it will be + replaced with a random string. +- `autoconnect` (boolean): don't display the login UI, immediately connect to + the server +- `ping` (number): interval in seconds to send PING commands. Set to 0 to + disable, this is the default. Enabling PINGs can have an impact on client + power usage and should only be enabled if necessary. + +## OAuth 2.0 + +The `oauth2` object configures OAuth 2.0 authentication. + +- `url` (string): OAuth 2.0 server URL. The server must support OAuth 2.0 + Authorization Server Metadata (RFC 8414) or OpenID Connect Discovery. +- `client_id` (string): OAuth 2.0 client ID. +- `client_secret` (string): OAuth 2.0 client secret. +- `scope` (string): OAuth 2.0 scope. diff --git a/doc/setup.md b/doc/setup.md new file mode 100644 index 0000000..5da4500 --- /dev/null +++ b/doc/setup.md @@ -0,0 +1,50 @@ +# Setting up gamja + +An HTTP server must be configured to serve the gamja static files. Usually, +the same HTTP server is used as a reverse proxy for the IRC WebSocket. + +## [soju] + +Add a WebSocket listener to soju, e.g. `listen wss://127.0.0.1:8080`. Then +configure your reverse proxy to serve gamja files and proxy `/socket` to soju. + +## [webircgateway] + +Setup webircgateway to serve gamja files: + +```ini +[fileserving] +enabled = true +webroot = /path/to/gamja +``` + +Then connect to webircgateway and append `?server=/webirc/websocket/` to the +URL. + +## nginx + +If you use nginx as a reverse HTTP proxy, make sure to bump the default read +timeout to a value higher than the IRC server PING interval. Example: + +``` +location / { + root /path/to/gamja; +} + +location /socket { + proxy_pass http://127.0.0.1:8080; + proxy_read_timeout 600s; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "Upgrade"; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_set_header X-Forwarded-Proto $scheme; +} +``` + +If you are unable to configure the proxy timeout accordingly, or if your IRC +server doesn't send PINGs, you can set the `server.ping` option in +`config.json` (see below). + +[soju]: https://soju.im +[webircgateway]: https://github.com/kiwiirc/webircgateway diff --git a/doc/url-params.md b/doc/url-params.md new file mode 100644 index 0000000..5912d78 --- /dev/null +++ b/doc/url-params.md @@ -0,0 +1,14 @@ +# URL parameters + +gamja settings can be overridden using URL query parameters: + +- `server`: path or URL to the WebSocket server +- `nick`: nickname +- `channels`: comma-separated list of channels to join (`#` needs to be escaped) +- `open`: [IRC URL] to open +- `debug`: if set to 1, debug mode is enabled + +Alternatively, the channels can be set with the URL fragment (ie, by just +appending the channel name to the gamja URL). + +[IRC URL]: https://datatracker.ietf.org/doc/html/draft-butcher-irc-url-04