]> git.mxchange.org Git - friendica.git/blob - doc/Config.md
Added documentation
[friendica.git] / doc / Config.md
1 Config values that can only be set in config/local.config.php
2 ==========================================================
3
4 * [Home](help)
5
6 Friendica's configuration is done in two places: in PHP array configuration files and in the `config` database table.
7 Database config values overwrite the same file config values.
8
9 ## File configuration
10
11 The configuration format for file configuration is an array returned from a PHP file.
12 This prevents your webserver from displaying your private configuration. It interprets the configuration files and displays nothing.
13
14 A typical configuration file looks like this:
15
16 ```php
17 <?php
18
19 /*
20  * Comment block
21  */
22
23 return [
24         'section1' => [
25                 // Comment line
26                 'key' => 'value',
27         ],
28         'section2' => [
29                 'array' => ['value0', 'value1', 'value2'],
30         ],
31 ];
32 ```
33
34 ### Configuration location
35
36 The `config` directory holds key configuration files and can have different config files.
37 All of them have to end with `.config.php` and must not include `-sample` in their name.
38
39 Some examples of common known configuration files:
40 - `local.config.php` holds the current node custom configuration.
41 - `addon.config.php` is optional and holds the custom configuration for specific addons.
42
43 Addons can define their own default configuration values in `addon/[addon]/config/[addon].config.php` which is loaded when the addon is activated.
44
45 ### Static Configuration location
46
47 The `static` directory holds the codebase default configurations files.
48 They must not be changed by users, because they can get changed from release to release.
49
50 Currently, the following configurations are included:
51 - `defaults.config.php` holds the default values for all the configuration keys that can only be set in `local.config.php`.
52 - `settings.config.php` holds the default values for some configuration keys that are set through the admin settings page.
53
54 #### Migrating from .htconfig.php to config/local.config.php
55
56 The legacy `.htconfig.php` configuration file is still supported, but is deprecated and will be removed in a subsequent Friendica release.
57
58 The migration is pretty straightforward:
59 If you had any addon-specific configuration in your `.htconfig.php`, just copy `config/addon-sample.config.php` to `config/addon.config.php` and move your configuration values.
60 Afterwards, copy `config/local-sample.config.php` to `config/local.config.php`, move the remaining configuration values to it according to the following conversion chart, then rename your `.htconfig.php` to check your node is working as expected before deleting it.
61
62 <style>
63 table.config {
64     margin: 1em 0;
65     background-color: #f9f9f9;
66     border: 1px solid #aaa;
67     border-collapse: collapse;
68     color: #000;
69     width: 100%;
70 }
71
72 table.config > tr > th,
73 table.config > tr > td,
74 table.config > * > tr > th,
75 table.config > * > tr > td {
76     border: 1px solid #aaa;
77     padding: 0.2em 0.4em
78 }
79
80 table.config > tr > th,
81 table.config > * > tr > th {
82     background-color: #f2f2f2;
83     text-align: center;
84     width: 50%
85 }
86 </style>
87
88 <table class="config">
89         <thead>
90                 <tr>
91                         <th>.htconfig.php</th>
92                         <th>config/local.config.php</th>
93                 </tr>
94         </thead>
95         <tbody>
96                 <tr>
97                         <td><pre>
98 $db_host = 'localhost';
99 $db_user = 'mysqlusername';
100 $db_pass = 'mysqlpassword';
101 $db_data = 'mysqldatabasename';
102 $a->config["system"]["db_charset"] = 'utf8mb4';
103 </pre></td>
104                         <td><pre>
105 'database' => [
106         'hostname' => 'localhost',
107         'username' => 'mysqlusername',
108         'password' => 'mysqlpassword',
109         'database' => 'database',
110         'charset' => 'utf8mb4',
111 ],
112 </pre></td>
113                 </tr>
114                 <tr>
115                         <td><pre>
116 $a->config["section"]["key"] = "value";
117 </pre></td>
118                         <td><pre>
119 'section' => [
120         'key' => 'value',
121 ],
122 </pre></td>
123                 </tr>
124                 <tr>
125                         <td><pre>
126 $a->config["section"]["key"] = array(
127         "value1",
128         "value2",
129         "value3"
130 );
131 </pre></td>
132                         <td><pre>
133 'section' => [
134         'key' => ['value1', 'value2', 'value3'],
135 ],
136 </pre></td>
137                 </tr>
138                 <tr>
139                         <td><pre>
140 $a->config["key"] = "value";
141 </pre></td>
142                         <td><pre>
143 'config' => [
144         'key' => 'value',
145 ],
146 </pre></td>
147                 </tr>
148                 <tr>
149             <td><pre>
150 $a->config['register_policy'] = REGISTER_CLOSED;
151 </pre></td>
152                     <td><pre>
153 'config' => [
154     'register_policy' => \Friendica\Module\Register::CLOSED,
155 ],
156 </pre></td>
157         </tr>
158                 <tr>
159                         <td><pre>
160 $a->path = "value";
161 </pre></td>
162                         <td><pre>
163 'system' => [
164         'urlpath' => 'value',
165 ],
166 </pre></td>
167                 </tr>
168                 <tr>
169                         <td><pre>
170 $default_timezone = "value";
171 </pre></td>
172                         <td><pre>
173 'system' => [
174         'default_timezone' => 'value',
175 ],
176 </pre></td>
177                 </tr>
178                 <tr>
179                         <td><pre>
180 $pidfile = "value";
181 </pre></td>
182                         <td><pre>
183 'system' => [
184         'pidfile' => 'value',
185 ],
186 </pre></td>
187                 </tr>
188                 <tr>
189                         <td><pre>
190 $lang = "value";
191 </pre></td>
192                         <td><pre>
193 'system' => [
194         'language' => 'value',
195 ],
196 </pre></td>
197                 </tr>
198         </tbody>
199 </table>
200
201 #### Migrating from config/local.ini.php to config/local.config.php
202
203 The legacy `config/local.ini.php` configuration file is still supported, but is deprecated and will be removed in a subsequent Friendica release.
204
205 The migration is pretty straightforward:
206 If you had any addon-specific configuration in your `config/addon.ini.php`, just copy `config/addon-sample.config.php` to `config/addon.config.php` and move your configuration values.
207 Afterwards, copy `config/local-sample.config.php` to `config/local.config.php`, move the remaining configuration values to it according to the following conversion chart, then rename your `config/local.ini.php` file to check your node is working as expected before deleting it.
208
209 <table class="config">
210         <thead>
211                 <tr>
212                         <th>config/local.ini.php</th>
213                         <th>config/local.config.php</th>
214                 </tr>
215         </thead>
216         <tbody>
217                 <tr>
218                         <td><pre>
219 [database]
220 hostname = localhost
221 username = mysqlusername
222 password = mysqlpassword
223 database = mysqldatabasename
224 charset = utf8mb4
225 </pre></td>
226                         <td><pre>
227 'database' => [
228         'hostname' => 'localhost',
229         'username' => 'mysqlusername',
230         'password' => 'mysqlpassword',
231         'database' => 'database',
232         'charset' => 'utf8mb4',
233 ],
234 </pre></td>
235                 </tr>
236                 <tr>
237                         <td><pre>
238 [section]
239 key = value
240 </pre></td>
241                         <td><pre>
242 'section' => [
243         'key' => 'value',
244 ],
245 </pre></td>
246                 </tr>
247                 <tr>
248             <td><pre>
249 [config]
250 register_policty = REGISTER_CLOSED
251 </pre></td>
252                                 <td><pre>
253 'config' => [
254     'register_policy' => \Friendica\Module\Register::CLOSED,
255 ],
256 </pre></td>
257         </tr>
258                 <tr>
259                         <td><pre>
260 [section]
261 key[] = value1
262 key[] = value2
263 key[] = value3
264 </pre></td>
265                         <td><pre>
266 'section' => [
267         'key' => ['value1', 'value2', 'value3'],
268 ],
269 </pre></td>
270                 </tr>
271         </tbody>
272 </table>
273
274
275
276 ### Database Settings
277
278 The configuration variables database.hostname, database.username, database.password, database.database and database.charset are holding your credentials for the database connection.
279 If you need to specify a port to access the database, you can do so by appending ":portnumber" to the database.hostname variable.
280
281     'database' => [
282         'hostname' => 'your.mysqlhost.com:123456',
283     ]
284
285 If all of the following environment variables are set, Friendica will use them instead of the previously configured variables for the db:
286
287     MYSQL_HOST
288     MYSQL_PORT
289     MYSQL_USERNAME
290     MYSQL_PASSWORD
291     MYSQL_DATABASE
292
293 ## Config values that can only be set in config/local.config.php
294
295 There are some config values that haven't found their way into the administration page.
296 This has several reasons.
297 Maybe they are part of a current development that isn't considered stable and will be added later in the administration page when it is considered safe.
298 Or it triggers something that isn't expected to be of public interest.
299 Or it is for testing purposes only.
300
301 **Attention:** Please be warned that you shouldn't use one of these values without the knowledge what it could trigger.
302 Especially don't do that with undocumented values.
303
304 These configurations keys and their default value are listed in `static/defaults.config.php` and should be overwritten in `config/local.config.php`.
305
306 ## Administrator Options
307
308 Enabling the admin panel for an account, and thus making the account holder admin of the node, is done by setting the variable
309
310     'config' => [
311         'admin_email' => 'someone@example.com',
312     ]
313     
314
315 Where you have to match the email address used for the account with the one you enter to the `config/local.config.php` file.
316 If more then one account should be able to access the admin panel, separate the email addresses with a comma.
317
318     'config' => [
319         'admin_email' => 'someone@example.com,someoneelse@example.com',
320     ]
321
322 If you want to have a more personalized closing line for the notification emails you can set a variable for the `admin_name`.
323
324     'config' => [
325         'admin_name' => 'Marvin',
326     ]