Skip to content

docs(installation): clarify automated setup with autoconfig.php #15403

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
joshtrichards wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs(installation): clarify automated setup with autoconfig.php #15403

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 76 additions & 54 deletions admin_manual/installation/automatic_configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

<?php
$AUTOCONFIG = [
Expand All @@ -50,9 +74,10 @@ Using the following parameter settings, the "Finish setup" screen requests datab
SQLite database
^^^^^^^^^^^^^^^

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

::
.. code-block:: php

<?php
$AUTOCONFIG = [
Expand All @@ -61,53 +86,54 @@ Using the following parameter settings, the "Finish setup" screen requests data
"dbtableprefix" => "",
];

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

<?php
$AUTOCONFIG = array(
$AUTOCONFIG = [
"dbtype" => "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

<?php
$AUTOCONFIG = array(
$AUTOCONFIG = [
"dbtype" => "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

<?php
$AUTOCONFIG = array(
$AUTOCONFIG = [
"dbtype" => "mysql",
"dbname" => "nextcloud",
"dbuser" => "username",
Expand All @@ -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`.
];

Loading