# HG changeset patch
# User Matthew Wild <mwild1@gmail.com>
# Date 1599828835 -3600
# Node ID 96838617695a59732dde3163625cedf32ae1d76f
# Parent  24f4eb35ab60e2535bede85d20ba4ee6fde941a8
mod_invites: Update documentation

diff -r 24f4eb35ab60 -r 96838617695a mod_invites/README.markdown
--- a/mod_invites/README.markdown	Fri Sep 11 13:53:43 2020 +0100
+++ b/mod_invites/README.markdown	Fri Sep 11 13:53:55 2020 +0100
@@ -1,21 +1,87 @@
+---
+labels:
+- 'Stage-Beta'
+summary: 'Invite management module for Prosody'
+...
+
+Introduction
+============
+
+This module is part of the suite of modules that implement invite-based
+account registration for Prosody. The other modules are:
+
+- mod_invites_adhoc
+- mod_invites_page
+- mod_invites_register
+- mod_invites_register_web
+- mod_register_apps
 
 This module manages the creation and consumption of invite codes for the
 host(s) it is loaded onto. It currently does not expose any admin/user-facing
 functionality (though in the future it will probably gain a way to view/manage
 pending invites).
 
-Other modules can use the API from this module to create invite tokens which
-can be used to e.g. register accounts or create automatic subscription approvals.
+Instead, other modules can use the API from this module to create invite tokens
+which can be used to e.g. register accounts or create automatic subscription
+approvals.
+
+This module should not be confused with the similarly named mod_invite (note the
+missing 's'!). That module was a precursor to this one that helped test and prove
+the concept of invite-based registration, and is now deprecated.
 
 # Configuration
 
+This module exposes just one option - the length of time that a generated invite
+should be valid for by default.
+
 ``` {.lua}
 -- Configure the number of seconds a token is valid for (default 7 days)
 invite_expiry = 86400 * 7
 ```
 
-Note that all modules that use this API will automatically load this module,
-so adding it to modules_enabled is generally not necessary.
+# Invites setup
+
+For a fully-featured invite-based setup, the following provides an example
+configuration:
+
+``` {.lua}
+-- Specify the external URL format of the invite links
+
+VirtualHost "example.com"
+    invites_page = "https://example.com/invite?{invite.token}"
+    http_external_url = "https://example.com/"
+    http_paths = {
+        invites_page = "/invite";
+        invites_register_web = "/register";
+    }
+    modules_enabled = {
+        "invites";
+        "invites_adhoc";
+        "invites_page";
+        "invites_register";
+        "invites_register_web";
+
+        "http_libjs"; -- See 'external dependencies' below
+    }
+```
+
+Restart Prosody and create a new invite using an ad-hoc command in an XMPP client connected
+to your admin account, or use the command line:
+
+    prosodyctl mod_invites generate example.com
+
+## External dependencies
+
+The default HTML templates for the web-based modules depend on some CSS and Javascript
+libraries. They expect these to be available at `https://example.com/share`. An easy
+way of doing this if you are on Debian 10 (buster) is to enable mod_http_libjs and install
+the following packages:
+
+    apt install libjs-bootstrap4 libjs-jquery
+
+On other systems you will need to manually put these libraries somewhere on the filesystem
+that Prosody can read, and serve them using mod_http_libjs with a custom `libjs_path`
+setting.
 
 # Compatibility