diff --git a/admin_manual/installation/images/install-wizard-a.png b/admin_manual/installation/images/install-wizard-a.png deleted file mode 100644 index cc6e166428d..00000000000 Binary files a/admin_manual/installation/images/install-wizard-a.png and /dev/null differ diff --git a/admin_manual/installation/images/install-wizard-a2.png b/admin_manual/installation/images/install-wizard-a2.png deleted file mode 100644 index 36dd8edca00..00000000000 Binary files a/admin_manual/installation/images/install-wizard-a2.png and /dev/null differ diff --git a/admin_manual/installation/images/install-wizard-autoconfig.png b/admin_manual/installation/images/install-wizard-autoconfig.png new file mode 100644 index 00000000000..922da56ed82 Binary files /dev/null and b/admin_manual/installation/images/install-wizard-autoconfig.png differ diff --git a/admin_manual/installation/images/install-wizard-firstrunwizard.png b/admin_manual/installation/images/install-wizard-firstrunwizard.png new file mode 100644 index 00000000000..89bc33c95cb Binary files /dev/null and b/admin_manual/installation/images/install-wizard-firstrunwizard.png differ diff --git a/admin_manual/installation/images/install-wizard-initial.png b/admin_manual/installation/images/install-wizard-initial.png new file mode 100644 index 00000000000..6de60b7100e Binary files /dev/null and b/admin_manual/installation/images/install-wizard-initial.png differ diff --git a/admin_manual/installation/installation_wizard.rst b/admin_manual/installation/installation_wizard.rst index 7747bde7349..220a3e5d06e 100644 --- a/admin_manual/installation/installation_wizard.rst +++ b/admin_manual/installation/installation_wizard.rst @@ -5,23 +5,28 @@ Installation wizard Quick start ----------- -When Nextcloud prerequisites are fulfilled and all Nextcloud files are installed, -the last step to completing the installation is running the Installation -Wizard. +When Nextcloud prerequisites are fulfilled and all Nextcloud files are installed, +the last step to completing the installation is running the Installation +Wizard. This is just three steps: #. Point your Web browser to ``http://localhost/nextcloud`` -#. Enter your desired administrator's username and password. -#. Click **Finish Setup**. +#. Enter your desired administration account name and password. +#. Click **Install**. -.. figure:: images/install-wizard-a.png +.. figure:: images/install-wizard-initial.png :scale: 75% - :alt: screenshot of the installation wizard - -You're finished and can start using your new Nextcloud server. + :alt: screenshot of the installation wizard -Of course, there is much more that you can do to set up your Nextcloud server for -best performance and security. In the following sections we will cover important +You're finished and can start using your new Nextcloud server. + +.. note:: + The wizard includes a real-time password strength indicator that rates your + chosen password from "too weak" to "extremely strong". For security, choose + a password rated at least "strong". + +Of course, there is much more that you can do to set up your Nextcloud server for +best performance and security. In the following sections we will cover important installation and post-installation steps. * :ref:`Data Directory Location ` @@ -33,85 +38,154 @@ installation and post-installation steps. Data directory location ----------------------- -Click **Storage and Database** to expose additional installation configuration -options for your Nextcloud data directory and database. +Expand the **Storage & database** section to expose additional installation +configuration options for your Nextcloud data directory and database. -.. figure:: images/install-wizard-a1.png - :scale: 75% - :alt: installation wizard with all options exposed - -You should locate your Nextcloud data directory outside of your Web root if you -are using an HTTP server other than Apache, or you may wish to store your -Nextcloud data in a different location for other reasons (e.g. on a storage -server). It is best to configure your data directory location at installation, -as it is difficult to move after installation. You may put it anywhere; in this -example is it located in ``/opt/nextcloud/``. This directory must already exist, +You should locate your Nextcloud data directory outside of your Web root if you +are using an HTTP server other than Apache, or you may wish to store your +Nextcloud data in a different location for other reasons (e.g. on a storage +server). It is best to configure your data directory location at installation, +as it is difficult to move after installation. You may put it anywhere; in this +example it is located in ``/opt/nextcloud/``. This directory must already exist, and must be owned by your HTTP user. +.. note:: + If the wizard detects that your ``.htaccess`` file is not working (for + example, because you are using Nginx or another non-Apache web server), it + will display a **Security warning** indicating that your data directory and + files may be accessible from the internet. Refer to the + :doc:`../installation/harden_server` documentation for guidance on + securing your data directory. + .. _database_choice_label: Database choice --------------- -SQLite is the default database for Nextcloud Server and it is good only for -testing and lightweight single-user setups without client synchronization. +SQLite is the default database for Nextcloud Server. When SQLite is selected, +the wizard displays a **Performance warning**: + + *SQLite should only be used for minimal and development instances. For + production we recommend a different database backend. If you use clients for + file syncing, the use of SQLite is highly discouraged.* + Supported databases are MySQL, MariaDB, Oracle, and PostgreSQL, and we recommend :doc:`MySQL/MariaDB `. Your database and PHP connectors must be installed before you run the Installation Wizard. When you install Nextcloud from packages all the necessary dependencies will be satisfied (see :doc:`source_installation` for a detailed listing of required -and optional PHP modules). You will need the root database login, or any -administrator login , and then enter any name you want for your Nextcloud database. -Be careful your administrator login needs to have the permissions to create -and modify databases and they needs to have the permissions to grant permissions -to other users. - -After you enter your root or administrator login for your database, the -installer creates a special database user with privileges limited to the -Nextcloud database. Then Nextcloud needs only the special Nextcloud database -user, and drops the root dB login. This user is named for your Nextcloud admin -user, with an ``oc_`` prefix, and then given a random password. The Nextcloud -database user and password are written into ``config.php``:: +and optional PHP modules). If only one database driver is available, the wizard +will show a notice and a link to the documentation on how to install additional +PHP modules. + +When you select a database other than SQLite, the wizard exposes additional +fields: + +* **Database user**: The username to connect to the database server. If this + user has sufficient privileges (e.g. the ability to query ``mysql.user`` for + MySQL, or the ``CREATEROLE`` privilege for PostgreSQL), the wizard will + attempt to create a dedicated Nextcloud database user with limited privileges + (see below). If the user lacks those privileges, the wizard gracefully falls + back to using the provided credentials directly. +* **Database password**: The password for the database user above. +* **Database name**: The name you want for your Nextcloud database. The wizard + will create it if it does not already exist and the user has + ``CREATE DATABASE`` privileges. +* **Database host**: The hostname (and optionally port) of your database + server, e.g. ``localhost`` or ``db.example.com:3306``. The default is + ``localhost``. You can also specify a Unix socket path here. The wizard + shows a helper hint: *"Please specify the port number along with the host + name (e.g., localhost:5432)."* +* **Database tablespace** *(Oracle only)*: Shown only when Oracle is selected. + +Automatic database user creation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When the provided database user has administrative privileges, the installer +attempts to create a dedicated database user with privileges limited to the +Nextcloud database. This avoids storing your administrative database credentials +in ``config.php``. + +If privileges are sufficient, the install creates a user named ``oc_admin``. +If that user already exists, a numeric suffix is appended (``oc_admin1``, +``oc_admin2``, etc.) until an available username is found. + +A random password is generated for the new user. The resulting credentials are +written into ``config.php``:: + + 'dbuser' => 'oc_admin', + 'dbpassword' => 'pX65Ty5DrHQkYPE5HRsDvyFHlZZHcm', + +If the provided user lacks the privileges to create new database users, the +installer falls back to using the provided credentials directly. + +.. tip:: + You can also explicitly prevent automatic user creation by setting the following + in your ``config.php`` before running the wizard (or via an autoconfig file):: + + 'setup_create_db_user' => false, + + This is useful when your database administrator has already created a dedicated + user for Nextcloud. In that case the wizard will use the database credentials + you provide directly, without attempting to create a new user or query + administrative privileges. + +Autoconfig +^^^^^^^^^^ + +If an autoconfig file is detected, the wizard displays a success notice: +*"Autoconfig file detected — The setup form below is pre-filled with the +values from the config file."* The **Storage & database** section is +automatically collapsed when the autoconfig provides valid values. For +details on autoconfig files, see :doc:`../configuration_server/automatic_configuration`. + +.. figure:: images/install-wizard-autoconfig.png + :scale: 75% + :alt: Nextcloud wizard screen when an autoconfig file is detected - 'dbuser' => 'oc_molly', - 'dbpassword' => 'pX65Ty5DrHQkYPE5HRsDvyFHlZZHcm', +Completing Installation +^^^^^^^^^^^^^^^^^^^^^^^ -Click Finish Setup, and start using your new Nextcloud server. +Click **Install**, and start using your new Nextcloud server. -.. figure:: images/install-wizard-a2.png +.. figure:: images/install-wizard-firstrunwizard.png :scale: 75% :alt: Nextcloud welcome screen after a successful installation Now we will look at some important post-installation steps. -.. _trusted_domains_label: +.. _trusted_domains_label: Trusted domains --------------- -All URLs used to access your Nextcloud server must be whitelisted in your -``config.php`` file, under the ``trusted_domains`` setting. Users -are allowed to log into Nextcloud only when they point their browsers to a -URL that is listed in the ``trusted_domains`` setting. This is not a -list of allowed client-side domains or IP addresses. -You may use IP addresses and domain names. +All URLs used to access your Nextcloud server must be whitelisted in your +``config.php`` file, under the ``trusted_domains`` setting. Users +are allowed to log into Nextcloud only when they point their browsers to a +URL that is listed in the ``trusted_domains`` setting. This is not a +list of allowed client-side domains or IP addresses. +You may use IP addresses and domain names. Wildcard patterns using ``*`` are +also supported (e.g. ``*.example.com``). A typical configuration looks like this:: - 'trusted_domains' => + 'trusted_domains' => array ( - 0 => 'localhost', - 1 => 'server1.example.com', + 0 => 'localhost', + 1 => 'server1.example.com', 2 => '192.168.1.50', 3 => '[fe80::1:50]', ), -Note: +.. note:: + + The loopback addresses ``localhost``, ``127.0.0.1``, and ``[::1]`` are + always treated as trusted regardless of the ``trusted_domains`` + configuration. This means that as long as you have access to the physical + server you can always log in. In the event that a load balancer or reverse + proxy is in place there will be no issues as long as it sends the correct + ``X-Forwarded-Host`` header. -The loopback address, ``127.0.0.1``, is automatically whitelisted, so as long -as you have access to the physical server you can always log in. In the event -that a load balancer is in place there will be no issues as long as it sends -the correct X-Forwarded-Host header. When a user tries a URL that -is not whitelisted the following error appears: +When a user tries a URL that is not whitelisted the following error appears: .. figure:: images/install-wizard-a4.png :scale: 75%