Mercurial > prosody-modules

annotate mod_invites/README.markdown @ 5734:cef8bce2d71b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
luacheck: Add new module API methods from trunk See * trunk rev 4d4f9e42bcf8 * trunk rev 65fb0d7a2312 * trunk rev c9ef35fab0b1
author Kim Alvefur <zash@zash.se>
date Mon, 27 Nov 2023 07:10:06 +0100
parents 2f7fff6c8c73
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4097
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
1 ---
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
2 labels:
5482
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody
Kim Alvefur <zash@zash.se>
parents: 4224
diff changeset
3 - 'Stage-Merged'
4097
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
4 summary: 'Invite management module for Prosody'
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
5 ...
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
6
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
7 Introduction
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
8 ============
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
9
5482
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody
Kim Alvefur <zash@zash.se>
parents: 4224
diff changeset
10 ::: {.alert .alert-info}
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody
Kim Alvefur <zash@zash.se>
parents: 4224
diff changeset
11 This module has been merged into Prosody as
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody
Kim Alvefur <zash@zash.se>
parents: 4224
diff changeset
12 [mod_invites][doc:modules:mod_invites]. Users of Prosody **0.12**
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody
Kim Alvefur <zash@zash.se>
parents: 4224
diff changeset
13 and later should not install this version.
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody
Kim Alvefur <zash@zash.se>
parents: 4224
diff changeset
14 :::
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody
Kim Alvefur <zash@zash.se>
parents: 4224
diff changeset
15
4097
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
16 This module is part of the suite of modules that implement invite-based
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
17 account registration for Prosody. The other modules are:
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
18
5482
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody
Kim Alvefur <zash@zash.se>
parents: 4224
diff changeset
19 - [mod_invites_adhoc][doc:modules:mod_invites_adhoc]
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody
Kim Alvefur <zash@zash.se>
parents: 4224
diff changeset
20 - [mod_invites_register][doc:modules:mod_invites_register]
4223
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4097
diff changeset
21 - [mod_invites_page]
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4097
diff changeset
22 - [mod_invites_register_web]
4224
816c2fa1ca84 mod_invites*: Also link to mod_invites_api
Kim Alvefur <zash@zash.se>
parents: 4223
diff changeset
23 - [mod_invites_api]
4223
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4097
diff changeset
24 - [mod_register_apps]
3776
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26 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
27 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
28 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
29 pending invites).
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30
4097
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
31 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: 3780
diff changeset
32 which can be used to e.g. register accounts or create automatic subscription
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
33 approvals.
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
34
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
35 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: 3780
diff changeset
36 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: 3780
diff changeset
37 the concept of invite-based registration, and is now deprecated.
3776
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
38
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39 # Configuration
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40
4097
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
41 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: 3780
diff changeset
42 should be valid for by default.
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
43
3780
824447fc7759 mod_invites/README: Fix code block syntax
Kim Alvefur <zash@zash.se>
parents: 3776
diff changeset
44 ``` {.lua}
3776
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
45 -- 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
46 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
47 ```
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
48
4097
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
49 # Invites setup
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
50
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
51 For a fully-featured invite-based setup, the following provides an example
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
52 configuration:
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
53
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
54 ``` {.lua}
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
55 -- Specify the external URL format of the invite links
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
56
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
57 VirtualHost "example.com"
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
58 invites_page = "https://example.com/invite?{invite.token}"
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
59 http_external_url = "https://example.com/"
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
60 http_paths = {
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
61 invites_page = "/invite";
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
62 invites_register_web = "/register";
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
63 }
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
64 modules_enabled = {
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
65 "invites";
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
66 "invites_adhoc";
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
67 "invites_page";
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
68 "invites_register";
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
69 "invites_register_web";
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
70
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
71 "http_libjs"; -- See 'external dependencies' below
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
72 }
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
73 ```
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
74
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
75 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: 3780
diff changeset
76 to your admin account, or use the command line:
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
77
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
78 prosodyctl mod_invites generate example.com
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
79
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
80 ## External dependencies
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
81
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
82 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: 3780
diff changeset
83 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: 3780
diff changeset
84 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: 3780
diff changeset
85 the following packages:
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
86
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
87 apt install libjs-bootstrap4 libjs-jquery
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
88
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
89 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: 3780
diff changeset
90 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: 3780
diff changeset
91 setting.
3776
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
92
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
93 # Compatibility
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
94
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
95 0.11 and later.