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