Mercurial > libervia-backend

comparison doc/configuration.rst @ 3021:8ec35cf13f66

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: added, overview, configuration and Primitivus documentation + some small modifications
author Goffi <goffi@goffi.org>
date Sun, 21 Jul 2019 22:14:30 +0200
parents
children 03fe31effa7f
comparison
equal deleted inserted replaced
3020:af9d71303605 3021:8ec35cf13f66
1 =============
2 Configuration
3 =============
4
5 Salut à Toi main configuration is set in a file named ``sat.conf`` (which may be prefixed
6 by a ``.`` if you want to hide it on suitable platforms). It is a common file used both by
7 backend and all frontends (and even related project like SàT Pubsub).
8
9 This file can located in the following paths (in order of parsing):
10 - ``/etc``
11 - ``~`` (``$HOME`` or your home directory)
12 - the directory where you are launching the backend or frontend from
13 - XDG directory for configuration (most of time it is
14 ``~/.config/sat/sat.conf``)
15
16 If several configurations files are found, they are merged. In case of conflict, the
17 option parsed last is the one used (in other words: if you have an option set in
18 ``/etc/sat.conf`` and the same one set in ``~/.sat.conf``, the one from ``~/.sat.conf``
19 will be used because it is parsed after ``/etc``).
20
21 Format
22 ======
23
24 ``sat.conf`` is a using the `INI`_ file format as understood by Python's
25 `SafeConfigParser`_ (meaning that you can use interpolation).
26
27 The ``DEFAULT`` section is used for global options, this is where you specify where are
28 your media.
29
30 Each frontend can have specific section with its name in lowercase (sections are case
31 sensitive), and some backend plugin can use specific sections too (usually named ``plugin
32 <plugin name>``). The ``pubsub`` section is used by ``SàT PubSub``. A section can also
33 have the name of a web site used with Libervia web framework.
34
35
36 To recapitulate, you can have the following sections in your ``sat.conf``:
37
38 ``[DEFAULT]``
39 the main, global section
40 frontend name (in lower case)
41 frontend specific settings. Some examples:
42
43 - ``[cagou]``
44 - ``[jp]``
45 - ``[primitivus]``
46 - ``[libervia]``
47 ``[plugin <plugin name>]``
48 backend plugin specific settings. Some examples:
49
50 - ``[plugin account]``
51 - ``[plugin muc]``
52 - ``[plugin search]``
53 ``[pubsub]``
54 SàT PubSub settings
55 ``[<website name>]``
56 the settings of a website for Libervia web framework
57
58 .. _INI: https://en.wikipedia.org/wiki/INI_file
59 .. _SafeConfigParser: https://docs.python.org/2/library/configparser.html
60
61 In the section, the option names suffixes are used to identify the type of settings:
62
63 - ``_dir`` is used to indicate a path to a directory
64 - ``_path`` is used to indicate a path (generally to a file, ``_dir`` being used for
65 directories)
66 - ``_int`` indicate a integer
67 - ``_list`` indicate a list comma-separated values
68 - ``_dict`` indicate a dictionary
69 - ``_json`` is used for complex data, represented with JSON format
70
71 Remember that if you want to span your data on several lines (which is often used with
72 ``*_dict`` or ``*_json`` options), you need to indent the extra lines and keep the same
73 indentation.
74
75 Sample
76 ======
77
78 Here is a configuration that you can use as a model to specify your own settings. Check
79 the comments to get the meaning of each option.
80
81 .. sourcecode:: cfg
82
83 [DEFAULT]
84 ; where SàT media are located
85 media_dir = ~/workspace/sat_media
86 log_level = debug
87 ; domain used for new accounts
88 xmpp_domain = example.net
89 ; list of profiles with admin rights
90 admins_list = toto,titi
91 ; settings to let the backend send emails
92 email_from = NOREPLY@example.net
93 email_server = localhost
94 # email_port =
95 # email_username =
96 # email_password =
97 # email_starttls = true
98 # email_auth = true
99 # email_admins_list = toto@example.net, titi@example.org
100 ; override DNS records
101 hosts_dict = {
102 "example.org": {"host": "127.0.0.1"}
103 }
104
105 [plugin account]
106 ; where a new account must be created
107 new_account_server = localhost
108 new_account_domain = example.net
109
110 [plugin muc]
111 ; default room to use in the "Join room" menu
112 default_muc = sat@chat.jabberfr.org
113
114 [primitivus]
115 log_level = debug
116 ; how the logs are formatted
117 ; note that "%" must be doubled here
118 log_fmt = %%(levelname)s: %%(message)s
119 ; use bracketed paste mode
120 bracketed_paste = true
121
122 [jp]
123 ; how to use xdotool to refresh Firefox when doing "jp blog edit"
124 blog_preview_open_cmd = firefox -new-tab {url}
125 blog_preview_update_cmd = /bin/sh -c "WID=$(xdotool search --name 'Mozilla Firefox' | head -1); xdotool windowactivate $WID; xdotool key F5"
126 ; and below the equivalent with Konqueror
127 # blog_preview_open_cmd = konqueror {url}
128 # blog_preview_update_cmd = /bin/sh -c "qdbus $(qdbus org.kde.konqueror\*) /konqueror/MainWindow_1 reload"
129
130 [libervia]
131 ; do we want "http", "https" or "both"?
132 connection_type = both
133 port = 8080
134 port_https = 8443
135 ; external port used for HTTPS (0 to use "port_https" value)
136 port_https_ext = 443
137 ; TLS public certificate or private key
138 ; and public certificate combined (PEM format)
139 tls_certificate = libervia.pem
140 ; TLS certificate private key (PEM format)
141 tls_private_key
142 ; if true (or 1), HTTP will redirect to HTTPS
143 redirect_to_https = 1
144 ; passphrase for libervia profile
145 passphrase = something_secure
146 ; here we redirect main libervia page
147 ; to the blog of a profile named "some_profile"
148 url_redirections_dict = {
149 "/": "/u/some_profile"
150 }