Mercurial > libervia-backend

comparison doc/apps.rst @ 4248:00852dd54695

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: documentation to create a Libervia app, first draft
author Goffi <goffi@goffi.org>
date Fri, 31 May 2024 11:08:18 +0200
parents
children
comparison
equal deleted inserted replaced
4247:4aa62767f501 4248:00852dd54695
1 .. _libervia-app-config:
2
3 =================================
4 Libervia App Configuration (YAML)
5 =================================
6
7 The Libervia application uses a YAML configuration file to define various aspects of the
8 application's behavior, environment, and settings.
9
10 The file will be parsed by `PyYAML`_ which is a full-featured YAML implementation. Check
11 its documentation for details.
12
13 Below is the documentation explaining the structure and functionality of each field in the
14 YAML file.
15
16 =================
17 Root-Level Fields
18 =================
19
20 - ``type``: Specifies the type of the application. See :ref:`libervia-app_type`.
21
22 - ``prepare``: Information required to prepare the environment. See :ref:`libervia-app_prepare`.
23
24 - ``files``: Specifies files to be created with defined content. See :ref:`libervia-app_files`.
25
26 - ``override``: Allows to override or add to default configurations. See :ref:`libervia-app_override`.
27
28 - ``expose``: Specifies configurations exposed to frontends or administrators. See :ref:`libervia-app_expose`.
29
30 ==================
31 Detailed Sections
32 ===================
33
34 .. _libervia-app_type:
35
36 type
37 ^^^^
38
39 Currently, the only supported type is ``docker-compose``.
40
41 .. _libervia-app_prepare:
42
43 prepare
44 ^^^^^^^
45
46 The ``prepare`` section specifies things like git repositories to be cloned before running the application.
47
48 Example
49 -------
50 Cloning the repository at `https://example.org/some/repository.git` to prepare the app:
51
52 .. code-block:: yaml
53
54 prepare:
55 git: https://example.org/some/repository.git
56
57 .. _libervia-app_files:
58
59 files
60 ^^^^^
61
62 The ``files`` section specifies additional files to be created for the application.
63
64 The YAML key is the name of the file to be created, and the content specified will
65 populate that file.
66
67 Example
68 -------
69 Creating a file named `settings-override.py` with the content `USE_X_FORWARDED_HOST = True`:
70
71 .. code-block:: yaml
72
73 files:
74 settings-override.py:
75 content: |
76 USE_X_FORWARDED_HOST = True
77
78 .. _libervia-app_override:
79
80 override
81 ^^^^^^^^
82
83 The ``override`` section allows for the specification or override of configurations. This
84 creates a ``docker-compose.override.yml`` file that will be merged with the default
85 ``docker-compose.yml``. For more information, see `Docker documentation
86 <https://docs.docker.com/compose/reference/#specifying-multiple-compose-files>`_.
87
88 Example
89 -------
90 Overriding the `ports` for the `example_app` service to expose port `8080`:
91
92 .. code-block:: yaml
93
94 override:
95 services:
96 example_app:
97 ports:
98 - "8080"
99
100 .. _libervia-app_expose:
101
102 Exposing Data
103 ^^^^^^^^^^^^^
104
105 The `expose` section specifies the configurations that are exposed to users or frontends.
106 See :ref:`libervia-app_param` for a reference of some exposed data. Ports and generated
107 passwords are exposed in dicts, respectively at the ``ports`` and ``passwords`` key.
108
109 .. _libervia-app_yaml-tags:
110
111 YAML Tags
112 ^^^^^^^^^
113
114 The following YAML tags can be used in the Libervia App configuration file:
115
116 .. _libervia-app_conf:
117
118 !libervia_conf
119 ++++++++++++++
120
121 Get a value from Libervia configuration. A list is expected with either:
122
123 - `name` of a config parameter
124 - `section` and `name` of a config parameter
125 - `section`, `name`, and `default` value of a config parameter
126 - `section`, `name`, `default` value, and `filter` (either `first` or `not`)
127
128 Filter options:
129
130 - `first`: get the first item of the value
131 - `not`: get the opposite value (to be used with booleans)
132
133 Example
134 -------
135 Getting a value from Libervia configuration:
136
137 .. code-block:: yaml
138
139 !libervia_conf [section, name, default]
140
141 .. _libervia-app_generate_pwd:
142
143 !libervia_generate_pwd
144 +++++++++++++++++++++
145
146 Generate a password and store it in persistent data. If the password has already been generated previously, it is reused.
147
148 Arguments:
149
150 - `name` (str) **required**: Name of the password. Will be used to store it so it kept
151 between restarts.
152 - `size` (int): Size of the password to generate. Default to 30
153
154 Example
155 -------
156 Generating a password named ``some_password`` with a size of 32 characters:
157
158 .. code-block:: yaml
159
160 !libervia_generate_pwd {name: some_password, size: 32}
161
162 .. _libervia-app_param:
163
164 !libervia_param
165 ++++++++++++++
166
167 Get a parameter specified when starting the application. The value can be either the name
168 of the parameter to get, or a list as `[name, default_value]`.
169
170
171
172 Available parameters:
173
174 url_prefix
175 The internal URL where the app will be served.
176 web_label
177 Label which will be used in Web frontend.
178 web_url_path
179 Public facing URL path which will be used in the web frontend to access the app.
180 web_external
181 If True, the web frontend will open the app in a separated page instead of embedding
182 it.
183 front_url
184 Whole URL to access the app. It is specified when the app has its own domain or
185 subdomain.
186
187 Example
188 -------
189 Getting a parameter:
190
191 .. code-block:: yaml
192
193 !libervia_param [url_prefix, /some_app]
194
195 .. _PyYAML: https://pyyaml.org/
196