From c9c2179a44a0b5c8d24a310b893999aa25e7159d Mon Sep 17 00:00:00 2001 From: Josh Date: Sat, 1 Aug 2026 17:11:12 -0400 Subject: [PATCH] docs(installation): clarifyt automated setup with autoconfig.php Signed-off-by: Josh --- .../installation/automatic_configuration.rst | 130 ++++++++++-------- 1 file changed, 76 insertions(+), 54 deletions(-) diff --git a/admin_manual/installation/automatic_configuration.rst b/admin_manual/installation/automatic_configuration.rst index 0daf341c566..ba7ee991a07 100644 --- a/admin_manual/installation/automatic_configuration.rst +++ b/admin_manual/installation/automatic_configuration.rst @@ -1,45 +1,69 @@ -=============== -Automatic setup -=============== +============================================== +Automated installation with ``autoconfig.php`` +============================================== + +Use :file:`config/autoconfig.php` to prefill, or fully automate, the web-based +initial setup of Nextcloud. This is useful when installing multiple identical +or similar instances. + +Create :file:`config/autoconfig.php` and include the installation parameters +that you want to prefill. Any values not provided in the file can be completed +in the setup form when you first launch Nextcloud. + +To complete the installation without interaction, provide a valid database +configuration, data directory, and both ``adminlogin`` and ``adminpass``. +Otherwise, Nextcloud displays the setup form so that missing or invalid values +can be corrected. + +Nextcloud removes :file:`config/autoconfig.php` after a successful +installation. The file remains in place if installation fails. + +.. note:: The supplied database account must be able to connect to the database + server and have sufficient privileges for the selected configuration. + Depending on the database backend and the account's privileges, Nextcloud may + create the database and a dedicated database user. Alternatively, create the + database and database user in advance, and grant the user the required + privileges, as described in + :doc:`../configuration_database/linux_database_configuration`. -If you need to install Nextcloud on multiple servers, you normally do not want -to set up each instance separately as described in -:doc:`../configuration_database/linux_database_configuration`. -For this reason, Nextcloud provides an automatic configuration feature. +.. warning:: ``autoconfig.php`` commonly contains plaintext database and + administrator passwords. Restrict access to the file before writing secrets + to it. If installation fails, remove the file or rotate any exposed secrets. -To take advantage of this feature, you must create a configuration file, called -:file:`config/autoconfig.php`, and set the file parameters as required. -You can specify any number of parameters in this file. Any unspecified parameters appear on the "Finish setup" screen when you first launch Nextcloud. +Parameters +---------- -The :file:`config/autoconfig.php` is automatically removed after the initial configuration has been applied. +The following parameters are commonly used: -.. note:: Keep in mind that the automatic configuration does not eliminate the need for - creating the database user and database in advance, as described in - :doc:`../configuration_database/linux_database_configuration`. +* ``directory`` (written to :file:`config.php` as ``datadirectory``) +* ``dbtype``, ``dbname``, ``dbuser``, ``dbpass``, ``dbhost``, and + ``dbtableprefix`` +* ``adminlogin`` and ``adminpass`` +* optionally, ``trusted_domains`` and ``adminemail`` -Parameters ----------- -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. +Two parameters have different names from their corresponding +:file:`config.php` settings: -+----------------+---------------+ -| autoconfig.php | config.php | -+================+===============+ -| directory | datadirectory | -+----------------+---------------+ -| dbpass | dbpassword | -+----------------+---------------+ ++--------------------+-------------------+ +| ``autoconfig.php`` | ``config.php`` | ++====================+===================+ +| ``directory`` | ``datadirectory`` | ++--------------------+-------------------+ +| ``dbpass`` | ``dbpassword`` | ++--------------------+-------------------+ -Automatic configurations examples ---------------------------------- +Examples +-------- -The following sections provide sample automatic configuration examples and what information is requested at the end of the configuration. +The following examples show partial and complete automatic configurations. Data Directory ^^^^^^^^^^^^^^ -Using the following parameter settings, the "Finish setup" screen requests database and admin credentials settings. +This configuration prefills the data directory. Complete the database and +administrator-account settings in the setup form. -:: +.. code-block:: php "", ]; -MySQL database -^^^^^^^^^^^^^^ +MySQL / MariaDB database +^^^^^^^^^^^^^^^^^^^^^^^^ -Using the following parameter settings, the "Finish setup" screen requests data directory and admin credentials settings. +This configuration prefills the MySQL or MariaDB settings. Complete the data +directory and administrator-account settings in the setup form. -:: +.. code-block:: php "mysql", "dbname" => "nextcloud", "dbuser" => "username", "dbpass" => "password", "dbhost" => "localhost", "dbtableprefix" => "", - ); + ]; PostgreSQL database ^^^^^^^^^^^^^^^^^^^ -Using the following parameter settings, the "Finish setup" screen requests data directory and admin credentials settings. +This configuration prefills the PostgreSQL settings. Complete the data +directory and administrator-account settings in the setup form. -:: +.. code-block:: php "pgsql", "dbname" => "nextcloud", "dbuser" => "username", "dbpass" => "password", "dbhost" => "localhost", "dbtableprefix" => "", - ); + ]; -.. note:: Keep in mind that the automatic configuration does not eliminate the need for - creating the database user and database in advance, as described in - :doc:`../configuration_database/linux_database_configuration`. +Complete non-interactive setup +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -All parameters -^^^^^^^^^^^^^^ +When all required values are present and valid, the installation proceeds +without requiring user interaction. -Using the following parameter settings, because all parameters are already configured in the file, the Nextcloud installation skips the "Finish setup" screen. +The following configuration bypasses the setup form: -:: +.. code-block:: php "mysql", "dbname" => "nextcloud", "dbuser" => "username", @@ -117,9 +143,5 @@ Using the following parameter settings, because all parameters are already confi "adminlogin" => "root", "adminpass" => "root-password", "directory" => "/www/htdocs/nextcloud/data", - ); - -.. note:: Keep in mind that the automatic configuration does not eliminate the need for - creating the database user and database in advance, as described in - :doc:`../configuration_database/linux_database_configuration`. + ];