From dfe90ce2e8d41b5c46e02dff1d582daf5dc84473 Mon Sep 17 00:00:00 2001 From: Joas Schilling Date: Fri, 15 Jan 2021 11:47:28 +0100 Subject: [PATCH] Adjust the manual to MySQL 8 required Signed-off-by: Joas Schilling --- .../linux_database_configuration.rst | 4 +- .../mysql_4byte_support.rst | 115 +++--------------- .../installation/source_installation.rst | 20 +-- .../installation/system_requirements.rst | 6 +- 4 files changed, 34 insertions(+), 111 deletions(-) diff --git a/admin_manual/configuration_database/linux_database_configuration.rst b/admin_manual/configuration_database/linux_database_configuration.rst index 48c528f76..bc62ef142 100644 --- a/admin_manual/configuration_database/linux_database_configuration.rst +++ b/admin_manual/configuration_database/linux_database_configuration.rst @@ -174,7 +174,7 @@ This just covers the SSL database configuration on the Nextcloud server. First y \PDO::MYSQL_ATTR_SSL_CA => '/../ca-cert.pem', \PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => true, ], - + Adjust the paths to the pem files for your environment. PostgreSQL database @@ -332,7 +332,7 @@ the respective host name:: +---------------+--------+ | Variable_name | Value | +---------------+--------+ - | version | 5.1.67 | + | version | 8.0.22 | +---------------+--------+ 1 row in set (0.00 sec) mysql> quit diff --git a/admin_manual/configuration_database/mysql_4byte_support.rst b/admin_manual/configuration_database/mysql_4byte_support.rst index 8803b28dc..796c069ee 100644 --- a/admin_manual/configuration_database/mysql_4byte_support.rst +++ b/admin_manual/configuration_database/mysql_4byte_support.rst @@ -9,65 +9,40 @@ Enabling MySQL 4-byte support In order to use Emojis (textbased smilies) on your Nextcloud server with a MySQL database, the installation needs to be tweaked a bit. -1. Make sure your database is set to use the Barracuda InnoDB file format (this is only needed on MySQL 5.x and MariaDB < 10.3): +.. note:: - Login to your mysql database and run:: + This manual only covers MySQL 8 or newer and MariaDB 10.3 or newer. If you use an older version, please check an older version of the documentation - mysql> show variables like 'innodb_file_format'; - +--------------------+-----------+ - | Variable_name | Value | - +--------------------+-----------+ - | innodb_file_format | Barracuda | - +--------------------+-----------+ - 1 row in set (0.00 sec) +1. Make sure the following InnoDB settings are set on your MySQL server:: - If your `innodb_file_format` is set as 'Antelope' you must upgrade your file format using:: + [mysqld] + innodb_file_per_table=1 - mysql> SET GLOBAL innodb_file_format=Barracuda; +Note:: - .. note:: + mysql> show variables like 'innodb_file_per_table'; + +-----------------------+-------+ + | Variable_name | Value | + +-----------------------+-------+ + | innodb_file_per_table | ON | + +-----------------------+-------+ + 1 row in set (0.00 sec) - On some shared hosts, you may not have the permissions to upgrade the InnoDB file format, meaning you are unable to use utf8mb4 - -2. Make sure the following InnoDB settings are set on your MySQL server: - - a. MySQL 8.0 or later:: - - [mysqld] - innodb_file_per_table=1 - - Note:: - - mysql> show variables like 'innodb_file_per_table'; - +-----------------------+-------+ - | Variable_name | Value | - +-----------------------+-------+ - | innodb_file_per_table | ON | - +-----------------------+-------+ - 1 row in set (0.00 sec) - - b. MySQL older than 8.0:: - - [mysqld] - innodb_large_prefix=true - innodb_file_format=barracuda - innodb_file_per_table=1 - -3. Open a shell, change dir (adjust ``/var/www/nextcloud`` to your nextcloud location if needed), and put your nextcloud instance in maintenance mode, if it isn't already:: +2. Open a shell, change dir (adjust ``/var/www/nextcloud`` to your nextcloud location if needed), and put your nextcloud instance in maintenance mode, if it isn't already:: $ cd /var/www/nextcloud $ sudo -u www-data php occ maintenance:mode --on -4. Restart the MySQL server in case you changed the configuration in step 1. -5. Change your databases character set and collation:: +3. Restart the MySQL server in case you changed the configuration in step 1. +4. Change your databases character set and collation:: ALTER DATABASE nextcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; -6. Set the ``mysql.utf8mb4`` config to true in your config.php:: +5. Set the ``mysql.utf8mb4`` config to true in your config.php:: $ sudo -u www-data php occ config:system:set mysql.utf8mb4 --type boolean --value="true" -7. Convert all existing tables to the new collation by running the repair step:: +6. Convert all existing tables to the new collation by running the repair step:: $ sudo -u www-data php occ maintenance:repair @@ -75,7 +50,7 @@ installation needs to be tweaked a bit. This will also change the `ROW_FORMAT` to `COMPRESSED` for your tables, to make sure the used database storage size is not getting out of hand. -8. Disable maintenance mode:: +7. Disable maintenance mode:: $ sudo -u www-data php occ maintenance:mode --off @@ -84,55 +59,3 @@ Now you should be able to use Emojis in your file names, calendar events, commen .. note:: Also make sure your backup strategy still work. If you use ``mysqldump`` make sure to add the ``--default-character-set=utf8mb4`` option. Otherwise your backups are broken and restoring them will result in ``?`` instead of the emojis, making files inaccessible. - -MariaDB support ---------------- - -MariaDB 10.3 or later -===================== -1. Make sure the following InnoDB settings are set on your MariaDB server:: - - [mysqld] - innodb_file_per_table=1 - -2. Restart the MariaDB server. - -3. Continue at step 3 of the **MySQL** instructions. - - -MariaDB 10.2 or earlier -======================= - -.. note:: - - All mysql statements have to be executed as privileged database user. (Using "normal" nextcloud database user will result in empty query sets due to missing privileges for INFORMATION_SCHEMA database.) - -1. Make sure the following InnoDB settings are set on your MySQL server:: - - [mysqld] - innodb_large_prefix=true - innodb_file_format=barracuda - innodb_file_per_table=1 - -2. Restart the MariaDB server. - -3. Figure out whether the file format was changed to Barracuda:: - - MariaDB> SELECT NAME, SPACE, FILE_FORMAT FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES WHERE NAME like "nextcloud%"; - -If the file format is "Barracuda" for every single table, nothing special is left to do. Continue with the MySQL instructions at step 3. While testing, all tables' file format was "Antelope". - -4. The tables needs to be migrated to "Barracuda" manually, one by one. SQL commands can be created easily, however:: - - MariaDB> USE INFORMATION_SCHEMA; - MariaDB> SELECT CONCAT("ALTER TABLE `", TABLE_SCHEMA,"`.`", TABLE_NAME, "` ROW_FORMAT=DYNAMIC;") AS MySQLCMD FROM TABLES WHERE TABLE_SCHEMA = "nextcloud"; - -This will return an SQL command for each table in the nextcloud database. The rows can be quickly copied into a text editor, the "|"s replaced and the SQL commands copied back to the MariaDB shell. If no error appeared (in doubt check step 2) all is done and nothing is left to do here. It can be proceded with the MySQL instructions from step 3 onwards. - -5. It is possible, however, that some tables cannot be altered. The operations fails with: "ERROR 1478 (HY000): Table storage engine 'InnoDB' does not support the create option 'ROW_FORMAT'". In that case the failing tables have a SPACE value of 0 in step 2. It basically means that the table does not have an index file of its own, which is required for the Barracuda format. This can be solved with a slightly different SQL command:: - - MariaDB> ALTER TABLE `nextcloud`.`oc_tablename` ROW_FORMAT=DYNAMIC, ALGORITHM=COPY; - -Replace oc_tablename with the failing table. If there are too many (did not happen here), SQL commands can be generated in a batch (task for the reader). - -6. Now everything should be fine and the MySQL instructions can be followed from step 3 onwards. diff --git a/admin_manual/installation/source_installation.rst b/admin_manual/installation/source_installation.rst index ec6f9c2f6..fd8ec4f63 100644 --- a/admin_manual/installation/source_installation.rst +++ b/admin_manual/installation/source_installation.rst @@ -33,7 +33,7 @@ If you get a result, the module is present. Required: -* PHP (7.2, 7.3 or 7.4) +* PHP (7.3 or 7.4) * PHP module ctype * PHP module curl * PHP module dom @@ -56,7 +56,7 @@ Database connectors (pick the one for your database:) * PHP module pdo_sqlite (>= 3, usually not recommended for performance reasons) * PHP module pdo_mysql (MySQL/MariaDB) -* PHP module pdo_pgsql (requires PostgreSQL >= 9.0) +* PHP module pdo_pgsql (PostgreSQL) *Recommended* packages: @@ -295,18 +295,18 @@ ini file. This can be the case, for example, for the ``date.timezone`` setting. **php.ini - used by the Web server:** :: - /etc/php/7.2/apache2/php.ini + /etc/php/7.4/apache2/php.ini or - /etc/php/7.2/fpm/php.ini + /etc/php/7.4/fpm/php.ini or ... **php.ini - used by the php-cli and so by Nextcloud CRON jobs:** :: - /etc/php/7.2/cli/php.ini + /etc/php/7.4/cli/php.ini .. note:: Path names have to be set in respect of the installed PHP - (>= 7.0, 7.1, 7.2 or 7.3) as applicable. + (>= 7.3 or 7.4) as applicable. .. _php_fpm_tips_label: @@ -326,7 +326,7 @@ Here are some example root paths for these ini/config files: +-----------------------+-----------------------+ | Debian/Ubuntu/Mint | CentOS/Red Hat/Fedora | +-----------------------+-----------------------+ -| ``/etc/php/7.2/fpm/`` | ``/etc/php-fpm.d/`` | +| ``/etc/php/7.4/fpm/`` | ``/etc/php-fpm.d/`` | +-----------------------+-----------------------+ In both examples, the ini/config file is called ``www.conf``, and depending on @@ -353,7 +353,7 @@ you must add them. Alternatively it is possible to use the environment variables of your system by modifying:: - /etc/php/7.2/fpm/pool.d/www.conf + /etc/php/7.4/fpm/pool.d/www.conf and uncommenting the line:: @@ -372,7 +372,7 @@ The best way to check your settings is with :ref:`label-phpinfo`. If you want to increase the maximum upload size, you will also have to modify your ``php-fpm`` configuration and increase the ``upload_max_filesize`` and -``post_max_size`` values. You will need to restart ``php5-fpm`` and your HTTP +``post_max_size`` values. You will need to restart ``php-fpm`` and your HTTP server in order for these changes to be applied. **.htaccess notes for Apache** @@ -453,7 +453,7 @@ To install the Nextcloud Snap Package, run the following command in a terminal:: Installation via web installer on a VPS or web space ---------------------------------------------------- -When you don't have access to the command line, for example at a web hosting or VMPS, +When you don't have access to the command line, for example at a web hosting or VMPS, an easy option is to use our web installer. This script can be found on our `server installation page here. `_ diff --git a/admin_manual/installation/system_requirements.rst b/admin_manual/installation/system_requirements.rst index 434ecb807..b8c6f50a2 100644 --- a/admin_manual/installation/system_requirements.rst +++ b/admin_manual/installation/system_requirements.rst @@ -29,7 +29,7 @@ For best performance, stability and functionality we have documented some recomm | Webserver | - **Apache 2.4 with** ``mod_php`` **or** ``php-fpm`` (recommended) | | | - nginx with ``php-fpm`` | +------------------+-----------------------------------------------------------------------+ -| PHP Runtime | - **7.3** (*recommended*) | +| PHP Runtime | - 7.3 | | | - **7.4** (*recommended*) | +------------------+-----------------------------------------------------------------------+ @@ -87,6 +87,6 @@ of a browser from this list, or one based on those: - Google **Chrome**/Chromium - Apple **Safari** -.. note:: If you want to use Nextcloud Talk you should use Mozilla **Firefox** 52+ or Google **Chrome**/Chromium 49+ to have - the full experience with video calls and screensharing. Google Chrome/Chromium requires an additional plugin for +.. note:: If you want to use Nextcloud Talk you should use Mozilla **Firefox** 52+ or Google **Chrome**/Chromium 49+ to have + the full experience with video calls and screensharing. Google Chrome/Chromium requires an additional plugin for screensharing.