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