doc/Config.md

   1 Config values that can only be set in config/local.ini.php
   2 ==========================================================
   3
   4 * [Home](help)
   5
   6 Friendica's configuration is done in two places: in INI configuration files and in the `config` database table.
   7 Database config values overwrite the same file config values.
   8
   9 ## File configuration
  10
  11 WARNING: some characters `?{}|&~![()^"` should not be used in the keys or values. If one of those character is required put the value between double quotes (eg. password = "let&me&in")
  12 The configuration format for file configuration is an INI string returned from a PHP file.
  13 This prevents your webserver from displaying your private configuration it interprets the configuration files and displays nothing.
  14
  15 A typical configuration file looks like this:
  16
  17 ```php
  18 <?php return <<<INI
  19
  20 ; Comment line
  21
  22 [section1]
  23 key = value
  24 empty_key =
  25
  26 [section2]
  27 array[] = value0
  28 array[] = value1
  29 array[] = value2
  30
  31 INI;
  32 // Keep this line
  33 ```
  34
  35 ### Configuration location
  36
  37 The `config` directory holds key configuration files:
  38
  39 - `config.ini.php` holds the default values for all the configuration keys that can only be set in `local.ini.php`.
  40 - `settings.ini.php` holds the default values for some configuration keys that are set through the admin settings page.
  41 - `local.ini.php` holds the current node custom configuration.
  42 - `addon.ini.php` is optional and holds the custom configuration for specific addons.
  43
  44 Addons can define their own default configuration values in `addon/[addon]/config/[addon].ini.php` which is loaded when the addon is activated.
  45
  46 #### Migrating from .htconfig.php to config/local.ini.php
  47
  48 The legacy `.htconfig.php` configuration file is still supported, but is deprecated and will be removed in a subsequent Friendica release.
  49
  50 The migration is pretty straightforward:
  51 If you had any addon-specific configuration in your `.htconfig.php`, just copy `config/addon-sample.ini.php` to `config/addon.ini.php` and move your configuration values.
  52 Afterwards, copy `config/local-sample.ini.php` to `config/local.ini.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.
  53
  54 <style>
  55 table.config {
  56     margin: 1em 0;
  57     background-color: #f9f9f9;
  58     border: 1px solid #aaa;
  59     border-collapse: collapse;
  60     color: #000;
  61     width: 100%;
  62 }
  63
  64 table.config > tr > th,
  65 table.config > tr > td,
  66 table.config > * > tr > th,
  67 table.config > * > tr > td {
  68     border: 1px solid #aaa;
  69     padding: 0.2em 0.4em
  70 }
  71
  72 table.config > tr > th,
  73 table.config > * > tr > th {
  74     background-color: #f2f2f2;
  75     text-align: center;
  76     width: 50%
  77 }
  78 </style>
  79
  80 <table class="config">
  81         <thead>
  82                 <tr>
  83                         <th>.htconfig.php</th>
  84                         <th>config/local.ini.php</th>
  85                 </tr>
  86         </thead>
  87         <tbody>
  88                 <tr>
  89                         <td><pre>
  90 $db_host = 'localhost';
  91 $db_user = 'mysqlusername';
  92 $db_pass = 'mysqlpassword';
  93 $db_data = 'mysqldatabasename';
  94 $a->config["system"]["db_charset"] = 'utf8mb4';
  95 </pre></td>
  96                         <td><pre>
  97 [database]
  98 hostname = localhost
  99 username = mysqlusername
 100 password = mysqlpassword
 101 database = mysqldatabasename
 102 charset = utf8mb4
 103 </pre></td>
 104                 </tr>
 105
 106                 <tr>
 107                         <td><pre>
 108 $a->config["section"]["key"] = "value";
 109 </pre></td>
 110                         <td><pre>
 111 [section]
 112 key = value
 113 </pre></td>
 114                 </tr>
 115
 116                 <tr>
 117                         <td><pre>
 118 $a->config["section"]["key"] = array(
 119         "value1",
 120         "value2",
 121         "value3"
 122 );
 123 </pre></td>
 124                         <td><pre>
 125 [section]
 126 key[] = value1
 127 key[] = value2
 128 key[] = value3
 129 </pre></td>
 130                 </tr>
 131
 132                 <tr>
 133                         <td><pre>
 134 $a->config["key"] = "value";
 135 </pre></td>
 136                         <td><pre>
 137 [config]
 138 key = value
 139 </pre></td>
 140                 </tr>
 141
 142                 <tr>
 143                         <td><pre>
 144 $a->path = "value";
 145 </pre></td>
 146                         <td><pre>
 147 [system]
 148 urlpath = value
 149 </pre></td>
 150                 </tr>
 151
 152                 <tr>
 153                         <td><pre>
 154 $default_timezone = "value";
 155 </pre></td>
 156                         <td><pre>
 157 [system]
 158 default_timezone = value
 159 </pre></td>
 160                 </tr>
 161
 162                 <tr>
 163                         <td><pre>
 164 $pidfile = "value";
 165 </pre></td>
 166                         <td><pre>
 167 [system]
 168 pidfile = value
 169 </pre></td>
 170                 </tr>
 171
 172                 <tr>
 173                         <td><pre>
 174 $lang = "value";
 175 </pre></td>
 176                         <td><pre>
 177 [system]
 178 language = value
 179 </pre></td>
 180                 </tr>
 181
 182         </tbody>
 183 </table>
 184
 185
 186 ### Database Settings
 187
 188 The configuration variables database.hostname, database.username, database.password, database.database and database.charset are holding your credentials for the database connection.
 189 If you need to specify a port to access the database, you can do so by appending ":portnumber" to the database.hostname variable.
 190
 191     [database]
 192     hostname = your.mysqlhost.com:123456
 193
 194 If all of the following environment variables are set, Friendica will use them instead of the previously configured variables for the db:
 195
 196     MYSQL_HOST
 197     MYSQL_PORT
 198     MYSQL_USERNAME
 199     MYSQL_PASSWORD
 200     MYSQL_DATABASE
 201
 202 ## Config values that can only be set in config/local.ini.php
 203
 204 There are some config values that haven't found their way into the administration page.
 205 This has several reasons.
 206 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.
 207 Or it triggers something that isn't expected to be of public interest.
 208 Or it is for testing purposes only.
 209
 210 **Attention:** Please be warned that you shouldn't use one of these values without the knowledge what it could trigger.
 211 Especially don't do that with undocumented values.
 212
 213 These configurations keys and their default value are listed in `config/config.ini.php` and should be ovewritten in `config/local.ini.php`.
 214
 215 ## Administrator Options
 216
 217 Enabling the admin panel for an account, and thus making the account holder admin of the node, is done by setting the variable
 218
 219     [config]
 220     admin_email = someone@example.com
 221
 222 Where you have to match the email address used for the account with the one you enter to the config/local.ini.php file.
 223 If more then one account should be able to access the admin panel, separate the email addresses with a comma.
 224
 225     [config]
 226     admin_email = someone@example.com,someoneelse@example.com
 227
 228 If you want to have a more personalized closing line for the notification emails you can set a variable for the admin_name.
 229
 230     [config]
 231     admin_name = Marvin