prosody-modules
d611ed13df7e
mod_invites/README.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Comparison

mod_invites/README.md @ 6209:d611ed13df7e draft

Merge
author Trần H. Trung <xmpp:trần.h.trung@trung.fun>
date Tue, 18 Mar 2025 00:16:25 +0700
parent 5482:mod_invites/README.markdown@2f7fff6c8c73
comparison
equal deleted inserted replaced
6208:e20901443eae 6209:d611ed13df7e
1 ---
2 labels:
3 - 'Stage-Merged'
4 summary: 'Invite management module for Prosody'
5 ...
6
7 Introduction
8 ============
9
10 ::: {.alert .alert-info}
11 This module has been merged into Prosody as
12 [mod_invites][doc:modules:mod_invites]. Users of Prosody **0.12**
13 and later should not install this version.
14 :::
15
16 This module is part of the suite of modules that implement invite-based
17 account registration for Prosody. The other modules are:
18
19 - [mod_invites_adhoc][doc:modules:mod_invites_adhoc]
20 - [mod_invites_register][doc:modules:mod_invites_register]
21 - [mod_invites_page]
22 - [mod_invites_register_web]
23 - [mod_invites_api]
24 - [mod_register_apps]
25
26 This module manages the creation and consumption of invite codes for the
27 host(s) it is loaded onto. It currently does not expose any admin/user-facing
28 functionality (though in the future it will probably gain a way to view/manage
29 pending invites).
30
31 Instead, other modules can use the API from this module to create invite tokens
32 which can be used to e.g. register accounts or create automatic subscription
33 approvals.
34
35 This module should not be confused with the similarly named mod_invite (note the
36 missing 's'!). That module was a precursor to this one that helped test and prove
37 the concept of invite-based registration, and is now deprecated.
38
39 # Configuration
40
41 This module exposes just one option - the length of time that a generated invite
42 should be valid for by default.
43
44 ``` {.lua}
45 -- Configure the number of seconds a token is valid for (default 7 days)
46 invite_expiry = 86400 * 7
47 ```
48
49 # Invites setup
50
51 For a fully-featured invite-based setup, the following provides an example
52 configuration:
53
54 ``` {.lua}
55 -- Specify the external URL format of the invite links
56
57 VirtualHost "example.com"
58 invites_page = "https://example.com/invite?{invite.token}"
59 http_external_url = "https://example.com/"
60 http_paths = {
61 invites_page = "/invite";
62 invites_register_web = "/register";
63 }
64 modules_enabled = {
65 "invites";
66 "invites_adhoc";
67 "invites_page";
68 "invites_register";
69 "invites_register_web";
70
71 "http_libjs"; -- See 'external dependencies' below
72 }
73 ```
74
75 Restart Prosody and create a new invite using an ad-hoc command in an XMPP client connected
76 to your admin account, or use the command line:
77
78 prosodyctl mod_invites generate example.com
79
80 ## External dependencies
81
82 The default HTML templates for the web-based modules depend on some CSS and Javascript
83 libraries. They expect these to be available at `https://example.com/share`. An easy
84 way of doing this if you are on Debian 10 (buster) is to enable mod_http_libjs and install
85 the following packages:
86
87 apt install libjs-bootstrap4 libjs-jquery
88
89 On other systems you will need to manually put these libraries somewhere on the filesystem
90 that Prosody can read, and serve them using mod_http_libjs with a custom `libjs_path`
91 setting.
92
93 # Compatibility
94
95 0.11 and later.