split admin FAQs

[friendica.git] / doc / Config.md

diff --git a/doc/Config.md b/doc/Config.md
index 788c1cd0b6c1fd38c997c76d7a93042a6320907f..8855099391d5dabd99fe4b4f9dd94fd0b0a0a8ef 100644 (file)
--- a/doc/Config.md
+++ b/doc/Config.md
@@ -1,55 +1,66 @@
-Config values that can only be set in config/local.ini.php
+Config values that can only be set in config/local.config.php

 ==========================================================
 
 * [Home](help)
 
 ==========================================================
 
 * [Home](help)
 

-Friendica's configuration is done in two places: in INI configuration files and in the `config` database table.
+Friendica's configuration is done in two places: in PHP array configuration files and in the `config` database table.

 Database config values overwrite the same file config values.
 
 ## File configuration
 
 Database config values overwrite the same file config values.
 
 ## File configuration
 

-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")
-The configuration format for file configuration is an INI string returned from a PHP file.
-This prevents your webserver from displaying your private configuration it interprets the configuration files and displays nothing.
+The configuration format for file configuration is an array returned from a PHP file.
+This prevents your webserver from displaying your private configuration. It interprets the configuration files and displays nothing.

 
 A typical configuration file looks like this:
 
 ```php
 
 A typical configuration file looks like this:
 
 ```php

-<?php return <<<INI
+<?php
+
+/*
+ * Comment block
+ */
+
+return [
+       'section1' => [
+               // Comment line
+               'key' => 'value',
+       ],
+       'section2' => [
+               'array' => ['value0', 'value1', 'value2'],
+       ],
+];
+```

 
 

-; Comment line
+### Configuration location

 
 

-[section1]
-key = value
-empty_key =
+The `config` directory holds key configuration files and can have different config files.
+All of them have to end with `.config.php` and must not include `-sample` in their name.

 
 

-[section2]
-array[] = value0
-array[] = value1
-array[] = value2
+Some examples of common known configuration files:
+- `local.config.php` holds the current node custom configuration.
+- `addon.config.php` is optional and holds the custom configuration for specific addons.

 
 

-INI;
-// Keep this line
-```
+Addons can define their own default configuration values in `addon/[addon]/config/[addon].config.php` which is loaded when the addon is activated.

 
 

-### Configuration location
+If needed, an alternative `config` path can be used by using the `FRIENDICA_CONFIG_DIR` environment variable (full path required!).
+This is useful in case of hardening the system by separating configuration from program binaries. 

 
 

-The `config` directory holds key configuration files:
+### Static Configuration location

 
 

-- `config.ini.php` holds the default values for all the configuration keys that can only be set in `local.ini.php`.
-- `settings.ini.php` holds the default values for some configuration keys that are set through the admin settings page.
-- `local.ini.php` holds the current node custom configuration.
-- `addon.ini.php` is optional and holds the custom configuration for specific addons.
+The `static` directory holds the codebase default configurations files.
+They must not be changed by users, because they can get changed from release to release.

 
 

-Addons can define their own default configuration values in `addon/[addon]/config/[addon].ini.php` which is loaded when the addon is activated.
+Currently, the following configurations are included:
+- `defaults.config.php` holds the default values for all the configuration keys that can only be set in `local.config.php`.
+- `settings.config.php` holds the default values for some configuration keys that are set through the admin settings page.

 
 

-#### Migrating from .htconfig.php to config/local.ini.php
+#### Migrating from .htconfig.php to config/local.config.php

 
 The legacy `.htconfig.php` configuration file is still supported, but is deprecated and will be removed in a subsequent Friendica release.
 
 The migration is pretty straightforward:
 
 The legacy `.htconfig.php` configuration file is still supported, but is deprecated and will be removed in a subsequent Friendica release.
 
 The migration is pretty straightforward:

-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.
-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.
+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.
+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.

 
 <style>
 table.config {
 
 <style>
 table.config {


@@ -81,7 +92,7 @@ table.config > * > tr > th {
        <thead>
                <tr>
                        <th>.htconfig.php</th>
        <thead>
                <tr>
                        <th>.htconfig.php</th>

-                       <th>config/local.ini.php</th>
+                       <th>config/local.config.php</th>

                </tr>
        </thead>
        <tbody>
                </tr>
        </thead>
        <tbody>


@@ -94,25 +105,25 @@ $db_data = 'mysqldatabasename';
 $a->config["system"]["db_charset"] = 'utf8mb4';
 </pre></td>
                        <td><pre>
 $a->config["system"]["db_charset"] = 'utf8mb4';
 </pre></td>
                        <td><pre>

-[database]
-hostname = localhost
-username = mysqlusername
-password = mysqlpassword
-database = mysqldatabasename
-charset = utf8mb4
+'database' => [
+       'hostname' => 'localhost',
+       'username' => 'mysqlusername',
+       'password' => 'mysqlpassword',
+       'database' => 'database',
+       'charset' => 'utf8mb4',
+],

 </pre></td>
                </tr>
 </pre></td>
                </tr>

-

                <tr>
                        <td><pre>
 $a->config["section"]["key"] = "value";
 </pre></td>
                        <td><pre>
                <tr>
                        <td><pre>
 $a->config["section"]["key"] = "value";
 </pre></td>
                        <td><pre>

-[section]
-key = value
+'section' => [
+       'key' => 'value',
+],

 </pre></td>
                </tr>
 </pre></td>
                </tr>

-

                <tr>
                        <td><pre>
 $a->config["section"]["key"] = array(
                <tr>
                        <td><pre>
 $a->config["section"]["key"] = array(


@@ -122,74 +133,157 @@ $a->config["section"]["key"] = array(
 );
 </pre></td>
                        <td><pre>
 );
 </pre></td>
                        <td><pre>

-[section]
-key[] = value1
-key[] = value2
-key[] = value3
+'section' => [
+       'key' => ['value1', 'value2', 'value3'],
+],

 </pre></td>
                </tr>
 </pre></td>
                </tr>

-

                <tr>
                        <td><pre>
 $a->config["key"] = "value";
 </pre></td>
                        <td><pre>
                <tr>
                        <td><pre>
 $a->config["key"] = "value";
 </pre></td>
                        <td><pre>

-[config]
-key = value
+'config' => [
+       'key' => 'value',
+],

 </pre></td>
                </tr>
 </pre></td>
                </tr>

-
+               <tr>
+            <td><pre>
+$a->config['register_policy'] = REGISTER_CLOSED;
+</pre></td>
+                    <td><pre>
+'config' => [
+    'register_policy' => \Friendica\Module\Register::CLOSED,
+],
+</pre></td>
+        </tr>

                <tr>
                        <td><pre>
 $a->path = "value";
 </pre></td>
                        <td><pre>
                <tr>
                        <td><pre>
 $a->path = "value";
 </pre></td>
                        <td><pre>

-[system]
-urlpath = value
+'system' => [
+       'urlpath' => 'value',
+],

 </pre></td>
                </tr>
 </pre></td>
                </tr>

-

                <tr>
                        <td><pre>
 $default_timezone = "value";
 </pre></td>
                        <td><pre>
                <tr>
                        <td><pre>
 $default_timezone = "value";
 </pre></td>
                        <td><pre>

-[system]
-default_timezone = value
+'system' => [
+       'default_timezone' => 'value',
+],

 </pre></td>
                </tr>
 </pre></td>
                </tr>

-

                <tr>
                        <td><pre>
 $pidfile = "value";
 </pre></td>
                        <td><pre>
                <tr>
                        <td><pre>
 $pidfile = "value";
 </pre></td>
                        <td><pre>

-[system]
-pidfile = value
+'system' => [
+       'pidfile' => 'value',
+],

 </pre></td>
                </tr>
 </pre></td>
                </tr>

-

                <tr>
                        <td><pre>
 $lang = "value";
 </pre></td>
                        <td><pre>
                <tr>
                        <td><pre>
 $lang = "value";
 </pre></td>
                        <td><pre>

-[system]
-language = value
+'system' => [
+       'language' => 'value',
+],

 </pre></td>
                </tr>
 </pre></td>
                </tr>

+       </tbody>
+</table>
+
+#### Migrating from config/local.ini.php to config/local.config.php

 
 

+The legacy `config/local.ini.php` configuration file is still supported, but is deprecated and will be removed in a subsequent Friendica release.
+
+The migration is pretty straightforward:
+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.
+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.
+
+<table class="config">
+       <thead>
+               <tr>
+                       <th>config/local.ini.php</th>
+                       <th>config/local.config.php</th>
+               </tr>
+       </thead>
+       <tbody>
+               <tr>
+                       <td><pre>
+[database]
+hostname = localhost
+username = mysqlusername
+password = mysqlpassword
+database = mysqldatabasename
+charset = utf8mb4
+</pre></td>
+                       <td><pre>
+'database' => [
+       'hostname' => 'localhost',
+       'username' => 'mysqlusername',
+       'password' => 'mysqlpassword',
+       'database' => 'database',
+       'charset' => 'utf8mb4',
+],
+</pre></td>
+               </tr>
+               <tr>
+                       <td><pre>
+[section]
+key = value
+</pre></td>
+                       <td><pre>
+'section' => [
+       'key' => 'value',
+],
+</pre></td>
+               </tr>
+               <tr>
+            <td><pre>
+[config]
+register_policty = REGISTER_CLOSED
+</pre></td>
+                               <td><pre>
+'config' => [
+    'register_policy' => \Friendica\Module\Register::CLOSED,
+],
+</pre></td>
+        </tr>
+               <tr>
+                       <td><pre>
+[section]
+key[] = value1
+key[] = value2
+key[] = value3
+</pre></td>
+                       <td><pre>
+'section' => [
+       'key' => ['value1', 'value2', 'value3'],
+],
+</pre></td>
+               </tr>

        </tbody>
 </table>
 
 
        </tbody>
 </table>
 
 

+

 ### Database Settings
 
 The configuration variables database.hostname, database.username, database.password, database.database and database.charset are holding your credentials for the database connection.
 If you need to specify a port to access the database, you can do so by appending ":portnumber" to the database.hostname variable.
 
 ### Database Settings
 
 The configuration variables database.hostname, database.username, database.password, database.database and database.charset are holding your credentials for the database connection.
 If you need to specify a port to access the database, you can do so by appending ":portnumber" to the database.hostname variable.
 

-    [database]
-    hostname = your.mysqlhost.com:123456
+    'database' => [
+        'hostname' => 'your.mysqlhost.com:123456',
+    ]

 
 If all of the following environment variables are set, Friendica will use them instead of the previously configured variables for the db:
 
 
 If all of the following environment variables are set, Friendica will use them instead of the previously configured variables for the db:
 


@@ -199,7 +293,7 @@ If all of the following environment variables are set, Friendica will use them i
     MYSQL_PASSWORD
     MYSQL_DATABASE
 
     MYSQL_PASSWORD
     MYSQL_DATABASE
 

-## Config values that can only be set in config/local.ini.php
+## Config values that can only be set in config/local.config.php

 
 There are some config values that haven't found their way into the administration page.
 This has several reasons.
 
 There are some config values that haven't found their way into the administration page.
 This has several reasons.


@@ -210,22 +304,26 @@ Or it is for testing purposes only.
 **Attention:** Please be warned that you shouldn't use one of these values without the knowledge what it could trigger.
 Especially don't do that with undocumented values.
 
 **Attention:** Please be warned that you shouldn't use one of these values without the knowledge what it could trigger.
 Especially don't do that with undocumented values.
 

-These configurations keys and their default value are listed in `config/config.ini.php` and should be ovewritten in `config/local.ini.php`.
+These configurations keys and their default value are listed in `static/defaults.config.php` and should be overwritten in `config/local.config.php`.

 
 ## Administrator Options
 
 Enabling the admin panel for an account, and thus making the account holder admin of the node, is done by setting the variable
 
 
 ## Administrator Options
 
 Enabling the admin panel for an account, and thus making the account holder admin of the node, is done by setting the variable
 

-    [config]
-    admin_email = someone@example.com
+    'config' => [
+        'admin_email' => 'someone@example.com',
+    ]
+    

 
 

-Where you have to match the email address used for the account with the one you enter to the config/local.ini.php file.
+Where you have to match the email address used for the account with the one you enter to the `config/local.config.php` file.

 If more then one account should be able to access the admin panel, separate the email addresses with a comma.
 
 If more then one account should be able to access the admin panel, separate the email addresses with a comma.
 

-    [config]
-    admin_email = someone@example.com,someoneelse@example.com
+    'config' => [
+        'admin_email' => 'someone@example.com,someoneelse@example.com',
+    ]

 
 

-If you want to have a more personalized closing line for the notification emails you can set a variable for the admin_name.
+If you want to have a more personalized closing line for the notification emails you can set a variable for the `admin_name`.

 
 

-    [config]
-    admin_name = Marvin
+    'config' => [
+        'admin_name' => 'Marvin',
+    ]