prosody-modules
8bfcedd93a72
mod_invites/README.markdown

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

Software / code / prosody-modules

Annotate

mod_invites/README.markdown @ 5551:8bfcedd93a72

mod_rest: List all error conditions in OpenAPI spec These are not handled by datamanager but by util.stanza and util.error, so they are not represented in the JSON schema file.
author Kim Alvefur <zash@zash.se>
date Sat, 17 Jun 2023 16:26:33 +0200
parent 5482:2f7fff6c8c73
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.