Move docs to a separate directory

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.

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

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