Mercurial > prosody-modules

annotate mod_invites/README.markdown @ 4211:0f26ae2f2a74

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_invites_page: Change client selection button text from 'Install' to 'Select' by default This also allows specific clients entries to override the text via the 'select_text' field. Rationale: 1) users may already have the software installed, we still want them to select it anyway for the tailored setup experience. 2) some clients (e.g. web clients) are not really "installed" so the text was misleading
author Matthew Wild <mwild1@gmail.com>
date Fri, 16 Oct 2020 11:06:25 +0100
parents 96838617695a
children 4ec755c13e9b
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:
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
3 - 'Stage-Beta'
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
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
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: 3780
diff changeset
11 account registration for Prosody. The other modules are:
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
12
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
13 - mod_invites_adhoc
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
14 - mod_invites_page
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
15 - mod_invites_register
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
16 - mod_invites_register_web
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
17 - 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
18
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19 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
20 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
21 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
22 pending invites).
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23
4097
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
24 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
25 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
26 approvals.
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
27
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
28 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
29 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
30 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
31
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
32 # Configuration
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
33
4097
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
34 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
35 should be valid for by default.
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
36
3780
824447fc7759 mod_invites/README: Fix code block syntax
Kim Alvefur <zash@zash.se>
parents: 3776
diff changeset
37 ``` {.lua}
3776
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
38 -- 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
39 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
40 ```
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41
4097
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
42 # Invites setup
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
43
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
44 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
45 configuration:
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
46
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
47 ``` {.lua}
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
48 -- Specify the external URL format of the invite links
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
49
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
50 VirtualHost "example.com"
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
51 invites_page = "https://example.com/invite?{invite.token}"
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
52 http_external_url = "https://example.com/"
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
53 http_paths = {
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
54 invites_page = "/invite";
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
55 invites_register_web = "/register";
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 modules_enabled = {
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
58 "invites";
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
59 "invites_adhoc";
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
60 "invites_page";
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
61 "invites_register";
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
62 "invites_register_web";
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 "http_libjs"; -- See 'external dependencies' below
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
65 }
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
66 ```
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
67
96838617695a mod_invites: Update documentation
Matthew Wild <mwild1@gmail.com>
parents: 3780
diff changeset
68 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
69 to your admin account, or use the command line:
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 prosodyctl mod_invites generate example.com
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 ## External dependencies
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 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
76 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
77 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
78 the following packages:
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 apt install libjs-bootstrap4 libjs-jquery
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 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
83 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
84 setting.
3776
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
85
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
86 # Compatibility
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
87
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
88 0.11 and later.