mirror of
https://codeberg.org/emersion/gamja
synced 2025-03-12 23:43:42 +01:00
Move docs to a separate directory
This commit is contained in:
Simon Ser
parent
68cb6c56c4
commit
ca4b3575b1
111
README.md
111
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
|
||||
|
||||
45
doc/config-file.md
Normal file
45
doc/config-file.md
Normal file
@ -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.
|
||||
50
doc/setup.md
Normal file
50
doc/setup.md
Normal file
@ -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
|
||||
14
doc/url-params.md
Normal file
14
doc/url-params.md
Normal file
@ -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
|
||||
Loading…
x
Reference in New Issue
Block a user