MoodleDocs - User contributions [en]

Installation quick guide

2020-12-22T03:33:25Z

Justineuro: corrected version name from change MOODLE_39_STABLE to MOODLE_310_STABLE

{{Installing Moodle}}
''This page is intended for administrators who are experienced with installing web server applications and are in a hurry to get up and running. Otherwise please see [[Installing Moodle]]''.

==Basic Requirements==

* You will need a working web server (e.g. [[Apache]]), a database (e.g. [[MySQL]], [[MariaDB]] or [[PostgreSQL]]) and have [[PHP]] configured. See the [{{Release notes}} release notes] in the dev docs for software requirements.
* Moodle requires a number of [[PHP]] extensions. However, Moodle checks early in the installation process and you can fix the problem and re-start the install script if any are missing.
* If you want Moodle to send email (you probably do) you need a working Sendmail (Unix/Linux) on your server or access to an SMTP mail server.

==Getting Moodle==

You have two basic options:
* Download your required version from https://download.moodle.org/ ... OR
* Pull the code from the Git repository (recommended for developers and also makes upgrading very simple):
<pre>
git clone -b MOODLE_310_STABLE git://git.moodle.org/moodle.git
</pre>
...this fetches a complete copy of the Moodle repository and then switches to the {{Version}} Stable branch.

See [[Git_for_Administrators|Git for Administrators ]] for details on using Git to install Moodle code.

Note: Only download Moodle from one of the moodle.org sources. Other versions (e.g. control panel based installers, Linux distribution repositories, other "one click" installers) cannot be guaranteed to work properly, be upgradable or be supportable.

==Create a database==

* Using your chosen database server, create a new empty database. The default encoding must be UTF8. For example, using MySQL:
<pre>
CREATE DATABASE moodle DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
</pre>
* Create a user/password combination with appropriate permissions for the database. For example (MySQL again):
<pre>
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,CREATE TEMPORARY TABLES,DROP,INDEX,ALTER ON moodle.* TO 'moodleuser'@'localhost' IDENTIFIED BY 'yourpassword';
</pre>

Notes: It is important to GRANT ON moodle.* as the database name including the '.*' and not just the bare database name. Save this password you use for the Moodle user, since you will need it later in the install.

==Create data directory==

* Create an empty directory to hold Moodle files. It '''must not''' be in the area served by the web server and must have permissions so that the web server user can write to it. Other than that it can be located anywhere. Typically, either make it owned by the web server user or give it write permissions for 'everyone'. If it is on a shared/NFS drive then read [[Caching]] - Moodle caches to this disk area by default and a slow share will mean terrible performance.

==Install Moodle code==

* If you downloaded the zip or tgz file earlier, then unzip / untar / move / copy the Moodle code (obtained above) so that it will be served by your web server (e.g. on Debian based Linux, move to /var/www/html/moodle)
* Check the permissions and make sure that the web server does '''not''' have permissions to write to any of the files in the Moodle code directories (a very common root cause of sites being hacked).
* If you need to, configure your web server to serve the Moodle site with your chosen URL.

==Configure Moodle==

* In the Moodle code directory, find the file ''config-dist.php'' and copy it to a new file called ''config.php'' (but read next step, 'Install Moodle', first).
* Edit config.php with your favourite editor and change the appropriate settings to point to your site, directories and database. ''Note: the Moodle install script will create config.php for you if it does not exist but make sure you (re-)set permissions appropriately afterwards''

==Install Moodle==

* Go to the URL for your moodle site in a browser (installation will complete automatically) or run the command line version at (requires cli version of PHP):
<pre>
/usr/bin/php /path/to/moodle/admin/cli/install.php
</pre>
The CLI creates the config.php for you and will not run if you created one in the previous step.
* After completing the install make sure your file permissions are ok for the Moodle program files (not writeable by web server) and the Moodle data files (writeable by web server).

==Set up cron==

You will need a cron job to run periodically. It is recommended that ''the cron is run every minute'', as required for asynchronous activity deletion when using the [[Recycle bin|recycle bin]]. A typical Unix cron entry will be as follows:
<pre>
* * * * * /usr/bin/php /path/to/moodle/admin/cli/cron.php >/dev/null
</pre>
Your site '''will not work properly''' unless cron is running regularly. It is very important you do not skip this step.

See [[Cron]] for details.

==Congratulations!==

You are now ready to use your Moodle site.

If you run into problems, check the [[Installation FAQ]] and visit the [http://moodle.org/mod/forum/view.php?id=28 Installation help forum].

[[Category:Quick guide]]

[[de:Installation in Kürze]]
[[fr:Installation_rapide]]
[[es:Inicio_Rápido_de_Instalación]]
[[ja:インストレーションクイックガイド]]

MySQL full unicode support

2020-08-06T04:44:34Z

Justineuro: added " = true" to "innodb_large_prefix"; mysql fails without setting it to true

{{Environment}}
==UTF-8==

UTF-8 is a character encoding that most websites use. It encodes each of the 1,112,064 valid code points. To store all of this information, four bytes is required. The most popular values are in the three byte region. MySQL by default only uses a three byte encoding and so values in the four byte range (eg. Asian characters and Emojis) can not be stored. Any attempt to enter a text that contains four byte characters will result in a Moodle database error.

MySQL does provide full four byte UTF-8 support, but it requires certain database settings to be configured. From version 3.3 on Moodle uses full UTF-8 for both MySQL and MariaDB by default. Existing databases will still run with partial support, but it is recommended to move over to full support.

Moodle comes with a Command Line Interface (CLI) script for converting to full UTF-8 for MySQL (and MariaDB). Before Moodle versions 3.1.5 and 3.2.2 this conversion tool would only change the Collation to some variant of 'utf8_bin'. 'utf8_unicode_ci' was the recommended Collation. We now recommend using 'utf8mb4_unicode_ci' which supports four byte characters (utf8_unicode_ci only supports three).

This script will attempt to change the database Collation, Character set, default table settings and column definitions.

To summarise:

* Fresh installs of Moodle 3.1.5 and 3.2.2 onwards will use utf8mb4 by default, if the database server is configured appropriately (see below).
* Sites upgrading to Moodle 3.1.5 or 3.2.2 can use the script to update to utf8mb4. In Moodle 3.3, 3.4 and 3.5 a warning will show that the database isn't using full UTF-8 support and suggest moving to 'utf8mb4_unicode_ci', but you may choose to keep using 'utf8_*'.

===File format===

To allow for large indexes on columns that are a varchar, a combination of settings needs to be set. The file format for the system needs to be using "Barracuda". This allows for the row format to be set to "Compressed" or "Dynamic". To enable this setting see the upgrade steps listed below. Moodle will not install if you have large format enabled without the Barracuda file format.

===File per table===

To enable this setting see the upgrade steps listed below.

===Large prefix===

This in conjunction with the row format being either "Compressed" or "Dynamic" allows for large varchar indexes above 191 characters.
To enable this setting see the upgrade steps listed below.

==Steps to upgrade==

Most important: Please backup your database before making any changes or running the CLI script.

* Change configuration settings for MySQL (exactly the same for MariaDB). This step is optional. You can run the script and it will try and make these changes itself. If errors occur then try manually changing these settings as listed below.
** On Linux based systems you will want to alter my.cnf. This may be located in '/etc/mysql/'.
** Make the following alterations to my.cnf:

Important Change; InnoDB: The following InnoDB file format configuration options were deprecated in MySQL 5.7.7 and are now removed:

innodb_file_format

innodb_file_format_check

innodb_file_format_max

innodb_large_prefix

<code>
[client]
default-character-set = utf8mb4

[mysqld]
innodb_file_format = Barracuda
innodb_file_per_table = 1
innodb_large_prefix = true

character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
skip-character-set-client-handshake

[mysql]
default-character-set = utf8mb4
</code>
* Restart your MySQL server.
* Run the CLI script to convert to the new Character set and Collation (requires Moodle 3.1.5, 3.2.2 or newer):
<pre>
$ php admin/cli/mysql_collation.php --collation=utf8mb4_unicode_ci
</pre>
* Make sure to repair and optimize all databases and tables.
<pre>
mysqlcheck -u root -p --auto-repair --optimize --all-databases
</pre>
NOTE: On very large sites this may take a long time to run. You should probably establish how long on a test install before taking your live site offline. In some cases you might consider dumping and re-importing your data.

* Adjust the $CFG->dboptions Array in your '''config.php''' to make sure that Moodle uses the right Collation when connecting to the MySQL Server:
<pre>
$CFG->dboptions = array(
…
'dbcollation' => 'utf8mb4_unicode_ci',
…
);
</pre>

If you only have access to the database command line (or something like phpmyadmin) you can try the following sql commands:
<code>
SET GLOBAL innodb_file_format = barracuda

SET GLOBAL innodb_file_per_table = 1

SET GLOBAL innodb_large_prefix = 'on'
</code>

* Try adding some Emojis (e.g. 😂💩) to your Moodle site to verify that the upgrade was successful.

[[Category:Environment|UTF-8]]
[[Category:UTF-8]]

[[es:MySQL soporte unicode completo]]
[[fr:Support unicode complet pour MySQL]]
[[de:MySQL Unicode Unterstützung]]