Mercurial > prosody-modules

comparison mod_invites/README.markdown @ 4097:96838617695a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_invites: Update documentation
author Matthew Wild <mwild1@gmail.com>
date Fri, 11 Sep 2020 13:53:55 +0100
parents 824447fc7759
children 4ec755c13e9b
comparison
equal deleted inserted replaced
4096:24f4eb35ab60 4097:96838617695a
1 ---
2 labels:
3 - 'Stage-Beta'
4 summary: 'Invite management module for Prosody'
5 ...
6
7 Introduction
8 ============
9
10 This module is part of the suite of modules that implement invite-based
11 account registration for Prosody. The other modules are:
12
13 - mod_invites_adhoc
14 - mod_invites_page
15 - mod_invites_register
16 - mod_invites_register_web
17 - mod_register_apps
1 18
2 This module manages the creation and consumption of invite codes for the 19 This module manages the creation and consumption of invite codes for the
3 host(s) it is loaded onto. It currently does not expose any admin/user-facing 20 host(s) it is loaded onto. It currently does not expose any admin/user-facing
4 functionality (though in the future it will probably gain a way to view/manage 21 functionality (though in the future it will probably gain a way to view/manage
5 pending invites). 22 pending invites).
6 23
7 Other modules can use the API from this module to create invite tokens which 24 Instead, other modules can use the API from this module to create invite tokens
8 can be used to e.g. register accounts or create automatic subscription approvals. 25 which can be used to e.g. register accounts or create automatic subscription
26 approvals.
27
28 This module should not be confused with the similarly named mod_invite (note the
29 missing 's'!). That module was a precursor to this one that helped test and prove
30 the concept of invite-based registration, and is now deprecated.
9 31
10 # Configuration 32 # Configuration
33
34 This module exposes just one option - the length of time that a generated invite
35 should be valid for by default.
11 36
12 ``` {.lua} 37 ``` {.lua}
13 -- Configure the number of seconds a token is valid for (default 7 days) 38 -- Configure the number of seconds a token is valid for (default 7 days)
14 invite_expiry = 86400 * 7 39 invite_expiry = 86400 * 7
15 ``` 40 ```
16 41
17 Note that all modules that use this API will automatically load this module, 42 # Invites setup
18 so adding it to modules_enabled is generally not necessary. 43
44 For a fully-featured invite-based setup, the following provides an example
45 configuration:
46
47 ``` {.lua}
48 -- Specify the external URL format of the invite links
49
50 VirtualHost "example.com"
51 invites_page = "https://example.com/invite?{invite.token}"
52 http_external_url = "https://example.com/"
53 http_paths = {
54 invites_page = "/invite";
55 invites_register_web = "/register";
56 }
57 modules_enabled = {
58 "invites";
59 "invites_adhoc";
60 "invites_page";
61 "invites_register";
62 "invites_register_web";
63
64 "http_libjs"; -- See 'external dependencies' below
65 }
66 ```
67
68 Restart Prosody and create a new invite using an ad-hoc command in an XMPP client connected
69 to your admin account, or use the command line:
70
71 prosodyctl mod_invites generate example.com
72
73 ## External dependencies
74
75 The default HTML templates for the web-based modules depend on some CSS and Javascript
76 libraries. They expect these to be available at `https://example.com/share`. An easy
77 way of doing this if you are on Debian 10 (buster) is to enable mod_http_libjs and install
78 the following packages:
79
80 apt install libjs-bootstrap4 libjs-jquery
81
82 On other systems you will need to manually put these libraries somewhere on the filesystem
83 that Prosody can read, and serve them using mod_http_libjs with a custom `libjs_path`
84 setting.
19 85
20 # Compatibility 86 # Compatibility
21 87
22 0.11 and later. 88 0.11 and later.