Move docs to a separate directory

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
+Then [configure an HTTP server] to serve the gamja files.
-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).
 
 ### 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:
+gamja can be configured via a [configuration file] and via [URL 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"
-	}
-}
-```
 
 ## 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

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