Skip to content

Commit c97cdbb

Browse files
susnuxsusnux
authored
Merge pull request #15403 from nextcloud/jtr/docs-autoconfig-fixes
docs(installation): clarify automated setup with autoconfig.php
2 parents 9a186a0 + c9c2179 commit c97cdbb

1 file changed

Lines changed: 76 additions & 54 deletions

File tree

‎admin_manual/installation/automatic_configuration.rst‎

Lines changed: 76 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,69 @@
1-
===============
2-
Automatic setup
3-
===============
1+
==============================================
2+
Automated installation with ``autoconfig.php``
3+
==============================================
4+
5+
Use :file:`config/autoconfig.php` to prefill, or fully automate, the web-based
6+
initial setup of Nextcloud. This is useful when installing multiple identical
7+
or similar instances.
8+
9+
Create :file:`config/autoconfig.php` and include the installation parameters
10+
that you want to prefill. Any values not provided in the file can be completed
11+
in the setup form when you first launch Nextcloud.
12+
13+
To complete the installation without interaction, provide a valid database
14+
configuration, data directory, and both ``adminlogin`` and ``adminpass``.
15+
Otherwise, Nextcloud displays the setup form so that missing or invalid values
16+
can be corrected.
17+
18+
Nextcloud removes :file:`config/autoconfig.php` after a successful
19+
installation. The file remains in place if installation fails.
20+
21+
.. note:: The supplied database account must be able to connect to the database
22+
server and have sufficient privileges for the selected configuration.
23+
Depending on the database backend and the account's privileges, Nextcloud may
24+
create the database and a dedicated database user. Alternatively, create the
25+
database and database user in advance, and grant the user the required
26+
privileges, as described in
27+
:doc:`../configuration_database/linux_database_configuration`.
428

5-
If you need to install Nextcloud on multiple servers, you normally do not want
6-
to set up each instance separately as described in
7-
:doc:`../configuration_database/linux_database_configuration`.
8-
For this reason, Nextcloud provides an automatic configuration feature.
29+
.. warning:: ``autoconfig.php`` commonly contains plaintext database and
30+
administrator passwords. Restrict access to the file before writing secrets
31+
to it. If installation fails, remove the file or rotate any exposed secrets.
932

10-
To take advantage of this feature, you must create a configuration file, called
11-
:file:`config/autoconfig.php`, and set the file parameters as required.
12-
You can specify any number of parameters in this file. Any unspecified parameters appear on the "Finish setup" screen when you first launch Nextcloud.
33+
Parameters
34+
----------
1335

14-
The :file:`config/autoconfig.php` is automatically removed after the initial configuration has been applied.
36+
The following parameters are commonly used:
1537

16-
.. note:: Keep in mind that the automatic configuration does not eliminate the need for
17-
creating the database user and database in advance, as described in
18-
:doc:`../configuration_database/linux_database_configuration`.
38+
* ``directory`` (written to :file:`config.php` as ``datadirectory``)
39+
* ``dbtype``, ``dbname``, ``dbuser``, ``dbpass``, ``dbhost``, and
40+
``dbtableprefix``
41+
* ``adminlogin`` and ``adminpass``
42+
* optionally, ``trusted_domains`` and ``adminemail``
1943

20-
Parameters
21-
----------
22-
When configuring parameters, you must understand that two parameters are named differently in this configuration file when compared to the standard :file:`config.php` file.
44+
Two parameters have different names from their corresponding
45+
:file:`config.php` settings:
2346

24-
+----------------+---------------+
25-
| autoconfig.php | config.php |
26-
+================+===============+
27-
| directory | datadirectory |
28-
+----------------+---------------+
29-
| dbpass | dbpassword |
30-
+----------------+---------------+
47+
+--------------------+-------------------+
48+
| ``autoconfig.php`` | ``config.php`` |
49+
+====================+===================+
50+
| ``directory`` | ``datadirectory`` |
51+
+--------------------+-------------------+
52+
| ``dbpass`` | ``dbpassword`` |
53+
+--------------------+-------------------+
3154

32-
Automatic configurations examples
33-
---------------------------------
55+
Examples
56+
--------
3457

35-
The following sections provide sample automatic configuration examples and what information is requested at the end of the configuration.
58+
The following examples show partial and complete automatic configurations.
3659

3760
Data Directory
3861
^^^^^^^^^^^^^^
3962

40-
Using the following parameter settings, the "Finish setup" screen requests database and admin credentials settings.
63+
This configuration prefills the data directory. Complete the database and
64+
administrator-account settings in the setup form.
4165

42-
::
66+
.. code-block:: php
4367
4468
<?php
4569
$AUTOCONFIG = [
@@ -50,9 +74,10 @@ Using the following parameter settings, the "Finish setup" screen requests datab
5074
SQLite database
5175
^^^^^^^^^^^^^^^
5276

53-
Using the following parameter settings, the "Finish setup" screen requests data directory and admin credentials settings.
77+
This configuration prefills the SQLite database settings. Complete the data
78+
directory and administrator-account settings in the setup form.
5479

55-
::
80+
.. code-block:: php
5681
5782
<?php
5883
$AUTOCONFIG = [
@@ -61,53 +86,54 @@ Using the following parameter settings, the "Finish setup" screen requests data
6186
"dbtableprefix" => "",
6287
];
6388
64-
MySQL database
65-
^^^^^^^^^^^^^^
89+
MySQL / MariaDB database
90+
^^^^^^^^^^^^^^^^^^^^^^^^
6691

67-
Using the following parameter settings, the "Finish setup" screen requests data directory and admin credentials settings.
92+
This configuration prefills the MySQL or MariaDB settings. Complete the data
93+
directory and administrator-account settings in the setup form.
6894

69-
::
95+
.. code-block:: php
7096
7197
<?php
72-
$AUTOCONFIG = array(
98+
$AUTOCONFIG = [
7399
"dbtype" => "mysql",
74100
"dbname" => "nextcloud",
75101
"dbuser" => "username",
76102
"dbpass" => "password",
77103
"dbhost" => "localhost",
78104
"dbtableprefix" => "",
79-
);
105+
];
80106
81107
PostgreSQL database
82108
^^^^^^^^^^^^^^^^^^^
83109

84-
Using the following parameter settings, the "Finish setup" screen requests data directory and admin credentials settings.
110+
This configuration prefills the PostgreSQL settings. Complete the data
111+
directory and administrator-account settings in the setup form.
85112

86-
::
113+
.. code-block:: php
87114
88115
<?php
89-
$AUTOCONFIG = array(
116+
$AUTOCONFIG = [
90117
"dbtype" => "pgsql",
91118
"dbname" => "nextcloud",
92119
"dbuser" => "username",
93120
"dbpass" => "password",
94121
"dbhost" => "localhost",
95122
"dbtableprefix" => "",
96-
);
123+
];
97124
98-
.. note:: Keep in mind that the automatic configuration does not eliminate the need for
99-
creating the database user and database in advance, as described in
100-
:doc:`../configuration_database/linux_database_configuration`.
125+
Complete non-interactive setup
126+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
101127

102-
All parameters
103-
^^^^^^^^^^^^^^
128+
When all required values are present and valid, the installation proceeds
129+
without requiring user interaction.
104130

105-
Using the following parameter settings, because all parameters are already configured in the file, the Nextcloud installation skips the "Finish setup" screen.
131+
The following configuration bypasses the setup form:
106132

107-
::
133+
.. code-block:: php
108134
109135
<?php
110-
$AUTOCONFIG = array(
136+
$AUTOCONFIG = [
111137
"dbtype" => "mysql",
112138
"dbname" => "nextcloud",
113139
"dbuser" => "username",
@@ -117,9 +143,5 @@ Using the following parameter settings, because all parameters are already confi
117143
"adminlogin" => "root",
118144
"adminpass" => "root-password",
119145
"directory" => "/www/htdocs/nextcloud/data",
120-
);
121-
122-
.. note:: Keep in mind that the automatic configuration does not eliminate the need for
123-
creating the database user and database in advance, as described in
124-
:doc:`../configuration_database/linux_database_configuration`.
146+
];
125147

0 commit comments

Comments
 (0)