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:
  37
  38 - `defaults.config.php` holds the default values for all the configuration keys that can only be set in `local.config.php`.
  39 - `settings.config.php` holds the default values for some configuration keys that are set through the admin settings page.
  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 #### Migrating from .htconfig.php to config/local.config.php
  46
  47 The legacy `.htconfig.php` configuration file is still supported, but is deprecated and will be removed in a subsequent Friendica release.
  48
  49 The migration is pretty straightforward:
  50 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.
  51 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.
  52
  53 <style>
  54 table.config {
  55     margin: 1em 0;
  56     background-color: #f9f9f9;
  57     border: 1px solid #aaa;
  58     border-collapse: collapse;
  59     color: #000;
  60     width: 100%;
  61 }
  62
  63 table.config > tr > th,
  64 table.config > tr > td,
  65 table.config > * > tr > th,
  66 table.config > * > tr > td {
  67     border: 1px solid #aaa;
  68     padding: 0.2em 0.4em
  69 }
  70
  71 table.config > tr > th,
  72 table.config > * > tr > th {
  73     background-color: #f2f2f2;
  74     text-align: center;
  75     width: 50%
  76 }
  77 </style>
  78
  79 <table class="config">
  80         <thead>
  81                 <tr>
  82                         <th>.htconfig.php</th>
  83                         <th>config/local.config.php</th>
  84                 </tr>
  85         </thead>
  86         <tbody>
  87                 <tr>
  88                         <td><pre>
  89 $db_host = 'localhost';
  90 $db_user = 'mysqlusername';
  91 $db_pass = 'mysqlpassword';
  92 $db_data = 'mysqldatabasename';
  93 $a->config["system"]["db_charset"] = 'utf8mb4';
  94 </pre></td>
  95                         <td><pre>
  96 'database' => [
  97         'hostname' => 'localhost',
  98         'username' => 'mysqlusername',
  99         'password' => 'mysqlpassword',
 100         'database' => 'database',
 101         'charset' => 'utf8mb4',
 102 ],
 103 </pre></td>
 104                 </tr>
 105                 <tr>
 106                         <td><pre>
 107 $a->config["section"]["key"] = "value";
 108 </pre></td>
 109                         <td><pre>
 110 'section' => [
 111         'key' => 'value',
 112 ],
 113 </pre></td>
 114                 </tr>
 115                 <tr>
 116                         <td><pre>
 117 $a->config["section"]["key"] = array(
 118         "value1",
 119         "value2",
 120         "value3"
 121 );
 122 </pre></td>
 123                         <td><pre>
 124 'section' => [
 125         'key' => ['value1', 'value2', 'value3'],
 126 ],
 127 </pre></td>
 128                 </tr>
 129                 <tr>
 130                         <td><pre>
 131 $a->config["key"] = "value";
 132 </pre></td>
 133                         <td><pre>
 134 'config' => [
 135         'key' => 'value',
 136 ],
 137 </pre></td>
 138                 </tr>
 139                 <tr>
 140             <td><pre>
 141 $a->config['register_policy'] = REGISTER_CLOSED;
 142 </pre></td>
 143                     <td><pre>
 144 'config' => [
 145     'register_policty' => REGISTER_CLOSED,
 146 ],
 147 </pre></td>
 148         </tr>
 149                 <tr>
 150                         <td><pre>
 151 $a->path = "value";
 152 </pre></td>
 153                         <td><pre>
 154 'system' => [
 155         'urlpath' => 'value',
 156 ],
 157 </pre></td>
 158                 </tr>
 159                 <tr>
 160                         <td><pre>
 161 $default_timezone = "value";
 162 </pre></td>
 163                         <td><pre>
 164 'system' => [
 165         'default_timezone' => 'value',
 166 ],
 167 </pre></td>
 168                 </tr>
 169                 <tr>
 170                         <td><pre>
 171 $pidfile = "value";
 172 </pre></td>
 173                         <td><pre>
 174 'system' => [
 175         'pidfile' => 'value',
 176 ],
 177 </pre></td>
 178                 </tr>
 179                 <tr>
 180                         <td><pre>
 181 $lang = "value";
 182 </pre></td>
 183                         <td><pre>
 184 'system' => [
 185         'language' => 'value',
 186 ],
 187 </pre></td>
 188                 </tr>
 189         </tbody>
 190 </table>
 191
 192 #### Migrating from config/local.ini.php to config/local.config.php
 193
 194 The legacy `config/local.ini.php` configuration file is still supported, but is deprecated and will be removed in a subsequent Friendica release.
 195
 196 The migration is pretty straightforward:
 197 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.
 198 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.
 199
 200 <table class="config">
 201         <thead>
 202                 <tr>
 203                         <th>config/local.ini.php</th>
 204                         <th>config/local.config.php</th>
 205                 </tr>
 206         </thead>
 207         <tbody>
 208                 <tr>
 209                         <td><pre>
 210 [database]
 211 hostname = localhost
 212 username = mysqlusername
 213 password = mysqlpassword
 214 database = mysqldatabasename
 215 charset = utf8mb4
 216 </pre></td>
 217                         <td><pre>
 218 'database' => [
 219         'hostname' => 'localhost',
 220         'username' => 'mysqlusername',
 221         'password' => 'mysqlpassword',
 222         'database' => 'database',
 223         'charset' => 'utf8mb4',
 224 ],
 225 </pre></td>
 226                 </tr>
 227                 <tr>
 228                         <td><pre>
 229 [section]
 230 key = value
 231 </pre></td>
 232                         <td><pre>
 233 'section' => [
 234         'key' => 'value',
 235 ],
 236 </pre></td>
 237                 </tr>
 238                 <tr>
 239             <td><pre>
 240 [config]
 241 register_policty = REGISTER_CLOSED
 242 </pre></td>
 243                                 <td><pre>
 244 'config' => [
 245     'register_policty' => REGISTER_CLOSED,
 246 ],
 247 </pre></td>
 248         </tr>
 249                 <tr>
 250                         <td><pre>
 251 [section]
 252 key[] = value1
 253 key[] = value2
 254 key[] = value3
 255 </pre></td>
 256                         <td><pre>
 257 'section' => [
 258         'key' => ['value1', 'value2', 'value3'],
 259 ],
 260 </pre></td>
 261                 </tr>
 262         </tbody>
 263 </table>
 264
 265
 266
 267 ### Database Settings
 268
 269 The configuration variables database.hostname, database.username, database.password, database.database and database.charset are holding your credentials for the database connection.
 270 If you need to specify a port to access the database, you can do so by appending ":portnumber" to the database.hostname variable.
 271
 272     'database' => [
 273         'hostname' => 'your.mysqlhost.com:123456',
 274     ]
 275
 276 If all of the following environment variables are set, Friendica will use them instead of the previously configured variables for the db:
 277
 278     MYSQL_HOST
 279     MYSQL_PORT
 280     MYSQL_USERNAME
 281     MYSQL_PASSWORD
 282     MYSQL_DATABASE
 283
 284 ## Config values that can only be set in config/local.config.php
 285
 286 There are some config values that haven't found their way into the administration page.
 287 This has several reasons.
 288 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.
 289 Or it triggers something that isn't expected to be of public interest.
 290 Or it is for testing purposes only.
 291
 292 **Attention:** Please be warned that you shouldn't use one of these values without the knowledge what it could trigger.
 293 Especially don't do that with undocumented values.
 294
 295 These configurations keys and their default value are listed in `config/defaults.config.php` and should be overwritten in `config/local.config.php`.
 296
 297 ## Administrator Options
 298
 299 Enabling the admin panel for an account, and thus making the account holder admin of the node, is done by setting the variable
 300
 301     'config' => [
 302         'admin_email' => 'someone@example.com',
 303     ]
 304
 305
 306 Where you have to match the email address used for the account with the one you enter to the `config/local.config.php` file.
 307 If more then one account should be able to access the admin panel, separate the email addresses with a comma.
 308
 309     'config' => [
 310         'admin_email' => 'someone@example.com,someoneelse@example.com',
 311     ]
 312
 313 If you want to have a more personalized closing line for the notification emails you can set a variable for the `admin_name`.
 314
 315     'config' => [
 316         'admin_name' => 'Marvin',
 317     ]