MoodleDocs - User contributions [en]

MUC FAQ

2016-05-09T07:46:45Z

Mrverrall: miscellaneous changes to (hopefully) improve readability.

{{Performance}}

The Moodle Unified Cache (MUC) on initial inspection can appear to be a complex off-putting beast and this can lead to it either being ignored or, as is often the case, poorly configured.

Here is what you need to know (so you can ignore [[Caching| the rest]]).

==What is the MUC?==

The MUC is a cache, a cache is a store of data which is easier/faster to retrieve than if it came from it's source. It saves (computing) effort and makes Moodle faster.

==Should I be using the MUC?==

Yes, and sites running Moodle 2.4 or above are already using the MUC.

If a site is already running fine then consider '''not changing anything''' as "[https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize premature optimization is the root of all evil]".

By default MUC uses the file system to store it's cached objects, this already speeds thing up greatly compared to using no MUC at all. By further configuring the MUC we are just trying to make it faster.

==What is wrong with the default file-system MUC?==

Not much at all, but the MUCs performance is dependant on the read/write speed of its storage medium.

Typically disks are slow but safe (persistent) storage. MUC data does not need to kept safe as it can always be regenerated and so can afford to be kept somewhere fast yet volatile, like RAM.

==How can I make MUC faster?==

Using a RAM based cache is the best way to make the MUC fast and there a few tools we can use to do this, such as, tmpfs, Memcached, APC, Redis and overtime probably more... A good place to start if unsure of any specific requirements is Memcached as it is common, well tested, fast and easy to deploy.

==How do I deploy Memcached==

This is by no means exhaustive, and will vary depending on the OS etc. But for simplicities sake...

* Install Memcached and it's PHP support in a way compatible with the operating system e.g. in Debian/Ubuntu
apt-get install memcached php5-memcached
* Confiure Memcached, or at least become aware of it's default setup, e.g.
** 64MB of RAM allocation
** Runs on port 11211
* In Moodle go to
**'Site administration > Plugins > Caching > Configuration'
**Under '''Installed cache stores''' look for Memcached and click the '''Add instance''' action.
**Give the store a name, like 'Memcached_MUC'
**In '''server''', assuming the basic config above, type 'localhost'. '''Save Changes'''.
**Scroll to the bottom of the '''Cache administration''' page.
**Under '''Stores used when no mapping is present''' click '''Edit Mappings'''.
**In the '''Application''' drop down select the caches name. '''Save Changes'''.
* Profit

See [[Caching]] for more details.

==How much memory should I allocate to MUC?==

The default on most Memcached deployments is 64MB and this is probably '''more''' than enough for a standard Moodle install. As a real world example, checking a live site with ~6000 individual user logins over the last 24 hours, was Memcached MUC usage was ~11MB (Moodle 2.8 with 26 additional plugins).

Most importantly when implementing an in memory cache such as Memcached is to monitor and understand its use in '''your own''' deployment as requirements can vary wildly.

==I'm already using Memcached for sessions, can I just reuse that?==

Nope, afraid not. If the MUC purges so will sessions, all users will be logged out. Two Memcached instances are required in this scenario, one for sessions and one MUC. An example of how to do this can be found [https://moopi.uk/course/view.php?id=4#section-5 here].

==How can I tell what Cache store I am really using==
[[File:perf.png|thumb|300px]]
Temporarily switch on performance debugging at,

''Site administration Development > Debugging > Performance info''.

This adds some useful information to the the footer of all pages (if your theme supports it) including MUC objects and the cachestore they came from .

==I have a cluster of servers, <further question here>?==

You are probably beyond the target audience of this FAQ in terms of your system administration foo.

==What is that little grey triangle?==
[[File:muc-triangle.png|thumb|300px]]
This appears under '''Stores used when no mapping is present''' when the default Application Cache store mapping does not support a requirement of one or more of the cache definitions.

For example, of the default application caches, '''Event Invalidation''' is not supported by Memcached. This is because Event Invalidation requires '''Data Guarantee''' which ensures data exists in the cache once it is put there. It is never cleaned up to free space or because it has not been recently used. Because Memcached evicts objects from it's cache it cannot be used for Event Invalidation.

This is not a problem as Event Invalidation will simply use the file-system cache, or if specified a compatible secondary application cache, or one allocated directly to the Event Invalidation definition.

==Where can I find more documentation on setting up the MUC?==

See [[Caching]].

If you are further interested in the nuts and bolts of the caching system, e.g. cache features (ttl, data guarantee, etc) the [https://github.com/moodle/moodle/blob/master/cache/README.md developers api] is a good place to look.

==See also==

* [https://moodle.org/mod/forum/discuss.php?d=323628 MUC and localcache] forum discussion

[[de:MUC FAQ]]

NTLM authentication

2016-02-02T13:50:51Z

Mrverrall: /* APACHE Configuration */

{{Authentication}}This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings. If you are using Moodle 2.4 or later, you can specify the format of the domain credentials (see below). If you are using an older version and you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Site Administration >> Plugins >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation==

No installation needed. See Site Administration >> Plugins >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*(Optionally) Set the "Remote username format" for your domain user credentials format (see below)
*On IIS: turn on Windows Authentication
*On Apache - use one of the 3 methods outlined below
*On the client pc's, you might need to set the moodle server ip/moodle url as being in "local intranet" (From IE, tools -> options -> security -> local intranet)

It is important to note the following conditions must be satisfied to let NTLM SSO happens:
*you've arrived to the login page with one GET request
*you've ldap->ntlmsso_enabled
*you've ldap->ntlmsso_subnet
*you aren't logged
*the IP of the client is in ntlmsso_subnet

Thus it is needed to set the IP subnet.

==How to Turn Integrated Authentication on==
The auth/ldap/ntlmsso_magic.php file MUST have NTLM/Integrated Authentication enabled on the server or the authentication will not work.

===IIS Configuration===
Open the IIS Management Console and navigate to the auth/ldap/ntlmsso_magic.php file.

====IIS 6.0====
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"

====IIS 7.x====
#After navigating to the 'auth/ldap' folder, switch to Content View
#right click on the file, choose "Switch to Features View"
#click on the Authentication icon on the right
#select 'Anonymous Authentication' and click the 'Disable' button
#select 'Windows Authentication' and click the 'Enable' button

*According to [http://moodle.org/mod/forum/discuss.php?d=145171#p634027 this post], if you are using IIS 7.5 (it comes with Windows Server 2008 R2), you have to select 'Windows Authentication' and click on 'Providers'. This shows a list of enabled providers (Negotiate and NTLM, by default). Change the order so that NTLM is at the top of the list.
*If 'Windows Authentication' is not available, then you need to install it as a separate authentication provider (in Control Panel).

===APACHE Configuration===
There are currently 4 possible methods for this:

====Using the NTLM part of Samba for Apache on Linux====
* If using Ubuntu 12.04 or higher you can install this using:
sudo apt-get install php5-ldap libapache2-mod-auth-ntlm-winbind winbind smbfs smbclient samba
sudo a2enmod auth_ntlm_winbind
sudo /etc/init.d/apache2 restart
Note: On Ubuntu 14.04 smbfs has been replaced with cifs-utils
* If you are using an earlier version of Ubuntu or another distribution you can get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups information from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file, inside the [global] section (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain.<br/> You'll need to type this account's password for the command to succeed.

: In Windows environments you could also try executing the command (as root):

# net join DOMAINNAME -S DCSERVER -U Administrator

: where DCSERVER is the Domain Controller server

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are going to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Stop and start the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core (and also in Redhat/Centos), keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138<br />
simply change the line to that was:
KeepAlive Off
to:
KeepAlive On
and restart apache (/etc/init.d/http restart)
* Here are some notes from people who have the samba winbind option working
::-- I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)
::-- I have this working on Ubuntu 8.04 LTS in an RM CC4 Active Directory Domain. [[User:munk3h|Ian]] 16:31 15 December 2009 (GMT)
::-- Running on Ubuntu 10.04 Lucid, Apache2 got this running in no time flat with AD v6. Worth noting that if Using Iñaki Arenaza's LDAP Clone plugin, you will need to add another copy of the Directory tag in <tt>apache2.conf</tt> pointing at the new ldap plugin. --[[User:Christopher O'Kelly|Christopher O'Kelly]] 10:09, 16 April 2012 (WST)
::-- On Ubuntu 14.04 I had to do the following to get NTLM auth working as I was getting the error "ntlm_auth reports Broken Helper: BH NT_STATUS_UNSUCCESSFUL NT_STATUS_UNSUCCESSFUL" in the Apache error logs (from [https://bugs.launchpad.net/ubuntu/+source/apache-mod-auth-ntlm-winbind/+bug/1304953 Launchpad]) [[User:ngmares|ngmares]]:

usermod -a -G winbindd_priv www-data
chgrp winbindd_priv /var/lib/samba/winbindd_privileged
ln -s /var/lib/samba/winbindd_privileged/pipe /var/run/samba/winbindd_privileged/pipe

====Using the NTLM Auth Module for Apache on Linux====
The NTLM Auth module is a bit stale and even its authors suggest that you use the [[#Using_the_NTLM_part_of_Samba_for_Apache_on_Linux|NTLM part of Samba with Apache on Linux]]

Get it from here
# get the Module from: http://modntlm.sourceforge.net/
# follow the instructions given there and inside the README that comes with the package.

I (Iñaki Arenaza) strongly recommend using the [[#Using_the_NTLM_part_of_Samba_for_Apache_on_Linux|NTLM part of Samba with Apache on Linux]] over this module. It's better maintained, more robust and has more features.

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

If you are using an x64 version of Apache mod_auth_sspi x64 versions are available from https://www.apachehaus.net/modules/mod_auth_sspi/

These files '''do not''' work with Apache versions 2.4.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain <YOUR AD DOMAIN>
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

Lastly for Internet Explorer 7 onwards you must also replace this line in your httpd-ssl.conf file:

BrowserMatch ".*MSIE.*" \

with

BrowserMatch ".*MSIE [2-5]\..*" \

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above) (http://grolmsnet.de/kerbtut/)

Environment details in this example:
#'''Active Directory Domain:''' EXAMPLE.AC.UK
#'''Active Directory Domain Controller:''' dc.example.ac.uk
#'''Linux/UNIX web server:''' moodle.example.ac.uk
#'''Active Directory user account for web server service principal:''' moodlekerb

Install kerberos on moodle.example.ac.uk and enter the following in krb5.conf (by default: /etc/krb5.conf)

<pre>
[libdefaults]
default_realm = EXAMPLE.AC.UK
[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}:
* Test kerberos
Issue the following command at the shell prompt:
<pre>
$> kinit user@EXAMPLE.AC.UK
</pre>

Where 'user' is an Active Directory account for which you know the password.

Next, issue the following:
<pre>$>klist</pre>
If all is OK it will list the Kerberos ticket you were granted from the domain controller (KDC)

* Create HTTP service principal for moodle.example.ac.uk
#Create the 'moodlekerb' '''user''' account in Active Directory (NOT a machine account) to map to the web server service principal (HTTP/moodle.example.ac.uk@EXAMPLE.AC.UK)
NOTE: moodle.example.ac.uk MUST be the canonical DNS name of the server i.e. an A record (NOT a CNAME). Additionally a valid PTR (reverse DNS) record must exist and match the corresponding A record.

#Use the ktpass.exe utility to map the service principal and create a keytab file
Apache requires a keytab file, which is generated with ktpass.exe on the Windows Active Directory Domain Controller.
Unfortunately, this component of Windows Server 2003 SP1 does not function correctly so one must obtain a hot fix: http://support.microsoft.com/kb/919557

Run the following command on the domain controller:
<pre>
C:\path\to\hotfix\ktpass.exe -princ HTTP/moodle.example.ac.uk@EXAMPLE.AC.UK -mapuser EXAMPLE\moodlekerb -crypto DES-CBC-MD5 +DesOnly +setPass +rndPass -ptype KRB5_NT_PRINCIPAL -out moodle.example.ac.uk.keytab
</pre>

Copy C:\path\to\hotfix\moodle.example.ac.uk.keytab to the moodle web server and remember the location (/etc/httpd/moodle.example.ac.uk.keytab or similar)

* Configure Apache / mod_auth_kerb
Edit the Apache configuration for the moodle host and add the following directives:
<pre>
<Directory /path/to/moodle/docs/auth/ldap/>
<Files ntlmsso_magic.php>
AuthName "Moodle"
AuthType Kerberos
KrbAuthRealms EXAMPLE.AC.UK
KrbServiceName HTTP
Krb5Keytab /etc/httpd/moodle.example.ac.uk.keytab
KrbMethodNegotiate on
KrbMethodK5Passwd on
KrbAuthoritative on
require valid-user
</Files>
</Directory>
</pre>

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.

* Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Configuring Domain user credentials format==
If you are using Moodle 2.4 and later there is a new setting that lets you configure the format of the domain user credentials, instead of using the old fixed format. The setting is called "Remote username format". If you leave this seting empty, the default '''DOMAINNAME\username''' format will be used. You can use the optional '''%domain%''' placeholder to specify where the domain name appears, and the mandatory '''%username%''' placeholder to specify where the username appears.

Some widely used formats are:
* '''%domain%\%username%''' : MS Windows default, contains the domain name, followed by a backlash character, followed by the username.
* '''%username%@%domain%''' : This is the same format used by Kerberos (domain name followed by an at sign, followed by the username).
* '''%domain%/%username%''' : Some people configure Samba+Winbind to use this format.
* '''%domain%+%username%''' : Some people configure Samba+Winbind to use this other format.
* '''%username%''' : Only contains the username, with no domain part.

==Notes/Tips==

#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.
# NTLM seems to not work at all when BASIC authentication is enabled. (this was using the Kerberos method, other ways may work)
# If the account in your AD management console shows like "First Last", you better change the ldap settings parameter 'User Attribute' from its default of {blank} / 'cn' to 'sAMAccountName' as indicated in [http://moodle.org/mod/forum/discuss.php?d=132364#p682173 this post]. The reason is that the cn name generally looks like "First Last", once you done the ldap sync, the user name in moodle will be "first last", but IE passes the account of "domain\first.last" to moodle which does not exist in moodle.

== To get a domain name for Moodle working on IIS7.5 Windows 2008 R2 ==
Refer to http://support.microsoft.com/kb/896861. Key section listed below.
Click Start, click Run, type regedit, and then click OK.<br />
In Registry Editor, locate and then click the following registry key:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\MSV1_0<br />
Right-click MSV1_0, point to New, and then click Multi-String Value.<br />
Type BackConnectionHostNames, and then press ENTER.<br />
Right-click BackConnectionHostNames, and then click Modify.<br />
In the Value data box, type the host name or the host names for the sites that are on the local computer, and then click OK.<br />
Quit Registry Editor, and then restart the IISAdmin service.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=186661 Moodle in a DMZ with NTLM] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]

[[Category:Contributed code]]

[[fr:Authentification NTLM]]

Installing Moodle

2015-12-01T15:50:38Z

Mrverrall: /* Set up your server */ typos

{{Template:Installing Moodle}}
''This page explains how to install Moodle. If you are an expert and/or in a hurry try [[Installation Quickstart]].''

If you just want to try Moodle on a standalone machine there are 'one-click' installers for Windows (see [[Complete install packages for Windows]]) and for OSX (see [[Complete Install Packages for Mac OS X]]) or [[ install on OS X]]. These are unsuitable for production servers.

== Requirements ==

Moodle is primarily developed in Linux using [[Apache]], [[PostgreSQL]]/[[MySQL]]/[[MariaDB]] and [[PHP]] (sometimes known as the LAMP platform). Typically this is also how Moodle is run, although there are other options as long as the software requirements of the [{{Release notes}} release] are met.

If you are installing Moodle in a Windows server, note that from php5.5 onwards, you will also need to have the Visual C++ Redistributable for Visual Studio 2012 installed from:
http://www.microsoft.com/en-us/download/details.aspx?id=30679 Visual C++] ( x86 or x64)

The basic requirements for Moodle are as follows:

=== Hardware ===
* Disk space: 200MB for the Moodle code, plus as much as you need to store content. 5GB is probably a realistic minimum.
* Processor: 1GHz (min), 2GHz dual core or more recommended.
* Memory: 512MB (min), 1GB or more is recommended.

All the above requirements will vary depending on specific hardware and software combinations as well as the type of use and load; busy sites may well require additional resources. Further guidance can be found under [[Performance_recommendations|performance recommendations]].

=== Software ===

See the [{{Release notes}} release notes] in the dev docs for software requirements.

== Set up your server ==

Depending the use case a Moodle server may be anything from a Desktop PC (e.g. for testing and evaluating) to a rackmounted or [[Server cluster|clustered]] solution. As mentioned above there are lots of possibilities for installing the basic server software, some links and pointers are at [[Installing AMP]], [[Internet_Information_Services|IIS]], [[Nginx]].

It will help hugely, regardless of your deployment choices, if time is taken to understand how to configure the different parts of your software stack (HTTP daemon, database, PHP etc). For example it is important that the HTTP daemon is configured to support [[Using slash arguments| slash arguments]].

If a hosting provider in being used ensure that all Moodle [{{Release notes}}#Server_requirements requirments] (such as PHP version) are met by the hosting platform, otherwise all the core configuration should be done. It will be helpful to become familiar with how to change setting within the hosting providers platform (e.g. PHP file upload maximums) as the options and tools provided can vary a huge amount between them.

== Download and copy files into place ==

'''IMPORTANT: While there are now a number of places you can get the Moodle code, you are strongly advised to obtain Moodle from moodle.org. If you run into problems it will be a great deal easier to support you.'''

You have two options:
* Download your required version from http://moodle.org/downloads and unzip/unpack...
* '''OR''' Pull the code from the Git repository (recommended for developers and also makes upgrading very simple):
<pre>
$ git clone --depth=1 -b MOODLE_30_STABLE git://git.moodle.org/moodle.git
</pre>
--depth=1 for shallow cloning (only) latest revision

--single-branch option to limit cloning to a single branch, this fetches the Moodle 3.0 Stable branch (latest weekly build). For a fuller discussion see [[Git for Administrators]].

Either of the above should result in a directory called '''moodle''', containing a number of files and folders.

You can either place the whole folder in your web server documents directory, in which case the site will be located at '''<nowiki>http://yourwebserver.com/moodle</nowiki>''', or you can copy all the contents straight into the main web server documents directory, in which case the site will be simply '''<nowiki>http://yourwebserver.com</nowiki>'''. See the documentation for your system and/or web server if you are unsure.

:''Tip:'' If you are downloading Moodle to your local computer and then uploading it to your hosted web site, if possible upload the compressed file and decompress at the remote end (check your 'file manager'). Failing that, watch FTP progress carefully for errors or missed files.

* '''Secure the Moodle files:''' It is vital that the files are not writeable by the web server user. For example, on Unix/Linux (as root):
<pre>
# chown -R root /path/to/moodle
# chmod -R 0755 /path/to/moodle
# find /path/to/moodle -type f -exec chmod 0644 {} \;
</pre>
(files are owned by the administrator/superuser and are only writeable by them - readable by everyone else)

The third command finds all the regular files and executes the chmod command 0644 on them.

If you want to use the built-in plugin installer you need to make the directory writable by web server user. It is strongly recommended to use ACL when your server supports it, for example if your Apache server uses account www-data:

<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodle
</pre>

The effect of the previous command is to allow the Apache user account (www-data in this case) to access and change files within the moodle site. Many people would consider this a brave move for a new site admin to implement. In a new moodle you can safely leave this out. A default Ubuntu install does not have the +a option for the chmod command anyway. The +a attribute is an ACL (Access Control List) facility which allows you to set per user access for individual files. For example, OSX has this by default.

== Create an empty database ==

Next create a new, empty database for your installation. You need to find and make a note of following information for use during the final installation stage:
* '''dbhost''' - the database server hostname. Probably ''localhost'' if the database and web server are the same machine, otherwise the name of the database server
* '''dbname''' - the database name. Whatever you called it, e.g. ''moodle''
* '''dbuser''' - the username for the database. Whatever you assigned, e.g. ''moodleuser'' - do not use the root/superuser account. Create a proper account with the minimum permissions needed.
* '''dbpass''' - the password for the above user

If your site is hosted you should find a web-based administration page for databases as part of the control panel (or ask your administrator). For everyone else or for detailed instructions, see the page for your chosen database server:
* [[PostgreSQL]]
* [[MariaDB]] (known issues - see MDL-45233)
* [[MySQL]] (known issues - see MDL-45233)
* [[MSSQL]]
* [[Oracle]] (known issues, not fully supported - see MDL-41310)

== Create the (''moodledata'') data directory ==

Moodle requires a directory to store all of its files (all your site's uploaded files, temporary data, cache, session data etc.). The web server needs to be able to write to this directory. On larger systems consider how much free space you are going to use when allocating this directory.

Due to the way Moodle caches data you may have performance issues if you use relatively slow storage (e.g. NFS) for this directory. Read the [[Performance_recommendations]] carefully and consider using (e.g.) memcached for [[Caching]].

'''IMPORTANT:''' This directory must '''NOT''' be accessible directly via the web. This would be a serious security hole. Do not try to place it inside your web root or inside your Moodle program files directory. Moodle will not install. It can go anywhere else convenient.

Here is an example (Unix/Linux) of creating the directory and setting the permissions for '''anyone''' on the server to write here. This is only appropriate for Moodle servers that are not shared. Discuss this with your server administrator for better permissions that just allow the web server user to access these files.

<pre>
# mkdir /path/to/moodledata
# chmod 0777 /path/to/moodledata
</pre>

If your server supports ACL it is recommended to set following permissions, for example if your Apache server uses account www-data:
<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>
If you are planning to execute PHP scripts from the command line you should set the same permissions for the current user:
<pre>
$ sudo chmod -R +a "`whoami` allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>

==== Securing moodledata in a web directory ====

If you are using a hosted site and you have no option but to place 'moodledata' in a web accessible directory. You may be able to secure it by creating an .htaccess file in the 'moodledata' directory. This does not work on all systems - see your host/administrator. Create a file called .htaccess containing only the following lines:
<pre>
order deny,allow
deny from all
</pre>

== Start Moodle install ==
It's now time to run the installer to create the database tables and configure your new site. The recommended method is to use the command line installer. If you cannot do this for any reason (e.g. on a Windows server) the web based installer is still available.

=== Command line installer ===

It's best to run the command line as your system's web user. You need to know what that is - see your system's documentation (e.g. Ubuntu/Debian is 'www-data', Centos is 'apache')

* Example of using the command-line (as root - substitute 'www-data' for your web user):
<pre>
# chown www-data /path/to/moodle
# cd /path/to/moodle/admin/cli
# sudo -u www-data /usr/bin/php install.php
# chown -R root /path/to/moodle
</pre>
The chowns allow the script to write a new config.php file. More information about the options can be found using
<pre>
# php install.php --help
</pre>

You will be asked for other settings that have not been discussed on this page - if unsure just accept the defaults. For a full discussion see [[Administration via command line]]

=== Web based installer ===
To run the web installer script, just go to your Moodle's main URL using a web browser.

The installation process will take you through a number of pages. You should be asked to confirm the copyright, see the database tables being created, supply administrator account details and supply the site details. The database creation can take some time - please be patient. You should eventually end up at the Moodle front page with an invitation to create a new course.

It is very likely that you will be asked to download the new config.php file and upload it to your Moodle installation - just follow the on-screen instructions.

==Final configuration==

=== Settings within Moodle ===
There are a number of options within the Moodle Site Administration screens (accessible from the 'Site administration' tab in the 'Administration' block. Here are a few of the more important ones that you will probably want to check:
* ''Administration > Site administration > Plugins > Message Outputs > Email'': Set your smtp server and authentication if required (so your Moodle site can send emails). The support contact for your site is also set on this page.
* ''Administration > Site administration > Server > System paths'': Set the paths to du, dot and aspell binaries.
* ''Administration > Site administration > Server > HTTP'': If you are behind a firewall you may need to set your proxy credentials in the 'Web proxy' section.
* ''Administration > Site administration > Location > Update timezones'': Run this to make sure your timezone information is up to date. (more info [[Location]])
** [http://php.net/manual/en/timezones.php Set server's local timezone] inside <tt>php.ini</tt> (should probably be inside <tt>/etc/php.ini</tt> or <tt>/etc/php.d/date.ini</tt>, depending on the underline OS):
**: <code ini>[Date]
; Defines the default timezone used by the date functions
date.timezone = "YOUR LOCAL TIMEZONE"</code>

=== Remaining tasks ===

* '''Configure Cron''': Moodle's background tasks (e.g. sending out forum emails and performing course backups) are performed by a script which you can set to execute at specific times of the day. This is known as a cron script. Please refer to the [[Cron|Cron instructions]].
* '''Set up backups''': See [[Site backup]] and [[Automated course backup]].
* '''Check mail works''': [[Add a new user|Create a test user]] with a valid email address and [[message|send them a message]]. Do they receive an email copy of the message? If not, check the settings in ''Settings > Site administration > Plugins > Message outputs > Email''. Don't be tempted to skip this step (clue: email is used to recover lost passwords, including the administrator password when you forget it!)
* '''Secure your Moodle site''': Read the [[Security recommendations]].
*'''Increasing the maximum upload size''' See [[Installation FAQ]] Maximum upload file size - how to change it?

=== Installation is complete :) ===

* Create a new course: You can now [[Adding a new course|create a new course]] and have a play ;-)

=== If something goes wrong... ===

Here are some things you should try...

* Check the [[Installation FAQ]]
* Check your file permissions carefully. Can your web server read (but not write) the Moodle program files? Can your web server read and write your Moodle data directory?
* Check your database permissions. Have you set up your database user with the correct rights and permissions for your configuration (especially if the web server and database server are different machines)?
* Create your [[Configuration file]] (config.php) by hand. Copy config-dist.php (in the root of the Moodle program directory) to config.php, edit it and set your database/site options there. Installation will continue from the right place.
* Once you have a config.php (see previous tip) you can edit it to turn on debugging (in section 8). This may give you extra information to help track down a problem. If you have access, check your web server error log(s).
* Re-check your php.ini / .htaccess settings. Are they appropriate (e.g. memory_limit), did you edit the correct php.ini / .htaccess file and (if required) did you re-start the web server after making changes?
* Did you include any non-core (optional) plugins, themes or other code before starting the installation script? If so, remove it and try again (it may be broken or incompatible).
* Explain your problem in the [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]. '''PLEASE''' list your software versions; explain what you did, what happened and what error messages you saw (if any); explain what you tried. There is no such thing as 'nothing', even a blank page is something!

== Platform specific instructions ==

'''Note:''' Much of this information is provided by the community. It may not have been checked and may be out of date. Please read in conjunction with the above installation instructions.

* [[Windows installation]]
** [[Installing Moodle on SmarterASP.NET]]
* [[Unix or Linux Installation]]
* [[Mac Installation]]
* [[Amazon EC2 Cloud Services Installation]]

== See also ==
* [http://www.slideshare.net/gb2048/my-own-moodle Slideshare presentation by Gareth Barnard on installing a local installation of Moodle] and accompanying [https://drive.google.com/folderview?id=0B17B0rYH2zERU21sQnVweUZCUFk&usp=sharing help guides]
* [http://moodle.org/mod/forum/discuss.php?d=182086 New Video Tutorial- How to Install Moodle on Shared Hosting via cPanel (Not Fantastico)]
* [http://moodle.org/mod/forum/discuss.php?d=199542 Video Tutorial - Install Moodle on a Virtual Box from scratch]

[[es:Instalaci%C3%B3n_de_moodle]]
[[de:Installation von Moodle]]
[[fr:Installation de Moodle]]
[[ja:Moodleのインストール]]

Installing Moodle

2015-11-30T16:36:20Z

Mrverrall: /* Set up your server */

{{Template:Installing Moodle}}
''This page explains how to install Moodle. If you are an expert and/or in a hurry try [[Installation Quickstart]].''

If you just want to try Moodle on a standalone machine there are 'one-click' installers for Windows (see [[Complete install packages for Windows]]) and for OSX (see [[Complete Install Packages for Mac OS X]]) or [[ install on OS X]]. These are unsuitable for production servers.

== Requirements ==

Moodle is primarily developed in Linux using [[Apache]], [[PostgreSQL]]/[[MySQL]]/[[MariaDB]] and [[PHP]] (sometimes known as the LAMP platform). Typically this is also how Moodle is run, although there are other options as long as the software requirements of the [{{Release notes}} release] are met.

If you are installing Moodle in a Windows server, note that from php5.5 onwards, you will also need to have the Visual C++ Redistributable for Visual Studio 2012 installed from:
http://www.microsoft.com/en-us/download/details.aspx?id=30679 Visual C++] ( x86 or x64)

The basic requirements for Moodle are as follows:

=== Hardware ===
* Disk space: 200MB for the Moodle code, plus as much as you need to store content. 5GB is probably a realistic minimum.
* Processor: 1GHz (min), 2GHz dual core or more recommended.
* Memory: 512MB (min), 1GB or more is recommended.

All the above requirements will vary depending on specific hardware and software combinations as well as the type of use and load; busy sites may well require additional resources. Further guidance can be found under [[Performance_recommendations|performance recommendations]].

=== Software ===

See the [{{Release notes}} release notes] in the dev docs for software requirements.

== Set up your server ==

Depending the use case a Moodle server may be anything from a Desktop PC (e.g. for testing and evaluating) to a rackmounted or [[Server cluster|clustered]] solution. As mentioned above there are lots of possibilities for installing the basic server software, some links and pointers are at [[Installing AMP]], [[Internet_Information_Services|IIS]], [[Nginx]].

It will help hugely, regardless of your deployment choices, if time is taken to understand how to configure the different parts of your software stack (HTTP daemon, database, PHP etc). For example it is important that the HTTP daemon is configured to support [[Using slash arguments| slash arguments]].

If a hosting provider in being used ensure that all Moodle [{{Release notes}}#Server_requirements requirments] (such as PHP version) are met by the hosting platform, otherwise all the core configuration should be done. I will be helpful to become familiar with how to change setting within the hosting providers platform (e.g. PHP file upload maximums) as the options and tools provided can vary a huge amount between then.

== Download and copy files into place ==

'''IMPORTANT: While there are now a number of places you can get the Moodle code, you are strongly advised to obtain Moodle from moodle.org. If you run into problems it will be a great deal easier to support you.'''

You have two options:
* Download your required version from http://moodle.org/downloads and unzip/unpack...
* '''OR''' Pull the code from the Git repository (recommended for developers and also makes upgrading very simple):
<pre>
$ git clone --depth=1 -b MOODLE_30_STABLE git://git.moodle.org/moodle.git
</pre>
--depth=1 for shallow cloning (only) latest revision

--single-branch option to limit cloning to a single branch, this fetches the Moodle 3.0 Stable branch (latest weekly build). For a fuller discussion see [[Git for Administrators]].

Either of the above should result in a directory called '''moodle''', containing a number of files and folders.

You can either place the whole folder in your web server documents directory, in which case the site will be located at '''<nowiki>http://yourwebserver.com/moodle</nowiki>''', or you can copy all the contents straight into the main web server documents directory, in which case the site will be simply '''<nowiki>http://yourwebserver.com</nowiki>'''. See the documentation for your system and/or web server if you are unsure.

:''Tip:'' If you are downloading Moodle to your local computer and then uploading it to your hosted web site, if possible upload the compressed file and decompress at the remote end (check your 'file manager'). Failing that, watch FTP progress carefully for errors or missed files.

* '''Secure the Moodle files:''' It is vital that the files are not writeable by the web server user. For example, on Unix/Linux (as root):
<pre>
# chown -R root /path/to/moodle
# chmod -R 0755 /path/to/moodle
# find /path/to/moodle -type f -exec chmod 0644 {} \;
</pre>
(files are owned by the administrator/superuser and are only writeable by them - readable by everyone else)

The third command finds all the regular files and executes the chmod command 0644 on them.

If you want to use the built-in plugin installer you need to make the directory writable by web server user. It is strongly recommended to use ACL when your server supports it, for example if your Apache server uses account www-data:

<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodle
</pre>

The effect of the previous command is to allow the Apache user account (www-data in this case) to access and change files within the moodle site. Many people would consider this a brave move for a new site admin to implement. In a new moodle you can safely leave this out. A default Ubuntu install does not have the +a option for the chmod command anyway. The +a attribute is an ACL (Access Control List) facility which allows you to set per user access for individual files. For example, OSX has this by default.

== Create an empty database ==

Next create a new, empty database for your installation. You need to find and make a note of following information for use during the final installation stage:
* '''dbhost''' - the database server hostname. Probably ''localhost'' if the database and web server are the same machine, otherwise the name of the database server
* '''dbname''' - the database name. Whatever you called it, e.g. ''moodle''
* '''dbuser''' - the username for the database. Whatever you assigned, e.g. ''moodleuser'' - do not use the root/superuser account. Create a proper account with the minimum permissions needed.
* '''dbpass''' - the password for the above user

If your site is hosted you should find a web-based administration page for databases as part of the control panel (or ask your administrator). For everyone else or for detailed instructions, see the page for your chosen database server:
* [[PostgreSQL]]
* [[MariaDB]] (known issues - see MDL-45233)
* [[MySQL]] (known issues - see MDL-45233)
* [[MSSQL]]
* [[Oracle]] (known issues, not fully supported - see MDL-41310)

== Create the (''moodledata'') data directory ==

Moodle requires a directory to store all of its files (all your site's uploaded files, temporary data, cache, session data etc.). The web server needs to be able to write to this directory. On larger systems consider how much free space you are going to use when allocating this directory.

Due to the way Moodle caches data you may have performance issues if you use relatively slow storage (e.g. NFS) for this directory. Read the [[Performance_recommendations]] carefully and consider using (e.g.) memcached for [[Caching]].

'''IMPORTANT:''' This directory must '''NOT''' be accessible directly via the web. This would be a serious security hole. Do not try to place it inside your web root or inside your Moodle program files directory. Moodle will not install. It can go anywhere else convenient.

Here is an example (Unix/Linux) of creating the directory and setting the permissions for '''anyone''' on the server to write here. This is only appropriate for Moodle servers that are not shared. Discuss this with your server administrator for better permissions that just allow the web server user to access these files.

<pre>
# mkdir /path/to/moodledata
# chmod 0777 /path/to/moodledata
</pre>

If your server supports ACL it is recommended to set following permissions, for example if your Apache server uses account www-data:
<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>
If you are planning to execute PHP scripts from the command line you should set the same permissions for the current user:
<pre>
$ sudo chmod -R +a "`whoami` allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>

==== Securing moodledata in a web directory ====

If you are using a hosted site and you have no option but to place 'moodledata' in a web accessible directory. You may be able to secure it by creating an .htaccess file in the 'moodledata' directory. This does not work on all systems - see your host/administrator. Create a file called .htaccess containing only the following lines:
<pre>
order deny,allow
deny from all
</pre>

== Start Moodle install ==
It's now time to run the installer to create the database tables and configure your new site. The recommended method is to use the command line installer. If you cannot do this for any reason (e.g. on a Windows server) the web based installer is still available.

=== Command line installer ===

It's best to run the command line as your system's web user. You need to know what that is - see your system's documentation (e.g. Ubuntu/Debian is 'www-data', Centos is 'apache')

* Example of using the command-line (as root - substitute 'www-data' for your web user):
<pre>
# chown www-data /path/to/moodle
# cd /path/to/moodle/admin/cli
# sudo -u www-data /usr/bin/php install.php
# chown -R root /path/to/moodle
</pre>
The chowns allow the script to write a new config.php file. More information about the options can be found using
<pre>
# php install.php --help
</pre>

You will be asked for other settings that have not been discussed on this page - if unsure just accept the defaults. For a full discussion see [[Administration via command line]]

=== Web based installer ===
To run the web installer script, just go to your Moodle's main URL using a web browser.

The installation process will take you through a number of pages. You should be asked to confirm the copyright, see the database tables being created, supply administrator account details and supply the site details. The database creation can take some time - please be patient. You should eventually end up at the Moodle front page with an invitation to create a new course.

It is very likely that you will be asked to download the new config.php file and upload it to your Moodle installation - just follow the on-screen instructions.

==Final configuration==

=== Settings within Moodle ===
There are a number of options within the Moodle Site Administration screens (accessible from the 'Site administration' tab in the 'Administration' block. Here are a few of the more important ones that you will probably want to check:
* ''Administration > Site administration > Plugins > Message Outputs > Email'': Set your smtp server and authentication if required (so your Moodle site can send emails). The support contact for your site is also set on this page.
* ''Administration > Site administration > Server > System paths'': Set the paths to du, dot and aspell binaries.
* ''Administration > Site administration > Server > HTTP'': If you are behind a firewall you may need to set your proxy credentials in the 'Web proxy' section.
* ''Administration > Site administration > Location > Update timezones'': Run this to make sure your timezone information is up to date. (more info [[Location]])
** [http://php.net/manual/en/timezones.php Set server's local timezone] inside <tt>php.ini</tt> (should probably be inside <tt>/etc/php.ini</tt> or <tt>/etc/php.d/date.ini</tt>, depending on the underline OS):
**: <code ini>[Date]
; Defines the default timezone used by the date functions
date.timezone = "YOUR LOCAL TIMEZONE"</code>

=== Remaining tasks ===

* '''Configure Cron''': Moodle's background tasks (e.g. sending out forum emails and performing course backups) are performed by a script which you can set to execute at specific times of the day. This is known as a cron script. Please refer to the [[Cron|Cron instructions]].
* '''Set up backups''': See [[Site backup]] and [[Automated course backup]].
* '''Check mail works''': [[Add a new user|Create a test user]] with a valid email address and [[message|send them a message]]. Do they receive an email copy of the message? If not, check the settings in ''Settings > Site administration > Plugins > Message outputs > Email''. Don't be tempted to skip this step (clue: email is used to recover lost passwords, including the administrator password when you forget it!)
* '''Secure your Moodle site''': Read the [[Security recommendations]].
*'''Increasing the maximum upload size''' See [[Installation FAQ]] Maximum upload file size - how to change it?

=== Installation is complete :) ===

* Create a new course: You can now [[Adding a new course|create a new course]] and have a play ;-)

=== If something goes wrong... ===

Here are some things you should try...

* Check the [[Installation FAQ]]
* Check your file permissions carefully. Can your web server read (but not write) the Moodle program files? Can your web server read and write your Moodle data directory?
* Check your database permissions. Have you set up your database user with the correct rights and permissions for your configuration (especially if the web server and database server are different machines)?
* Create your [[Configuration file]] (config.php) by hand. Copy config-dist.php (in the root of the Moodle program directory) to config.php, edit it and set your database/site options there. Installation will continue from the right place.
* Once you have a config.php (see previous tip) you can edit it to turn on debugging (in section 8). This may give you extra information to help track down a problem. If you have access, check your web server error log(s).
* Re-check your php.ini / .htaccess settings. Are they appropriate (e.g. memory_limit), did you edit the correct php.ini / .htaccess file and (if required) did you re-start the web server after making changes?
* Did you include any non-core (optional) plugins, themes or other code before starting the installation script? If so, remove it and try again (it may be broken or incompatible).
* Explain your problem in the [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]. '''PLEASE''' list your software versions; explain what you did, what happened and what error messages you saw (if any); explain what you tried. There is no such thing as 'nothing', even a blank page is something!

== Platform specific instructions ==

'''Note:''' Much of this information is provided by the community. It may not have been checked and may be out of date. Please read in conjunction with the above installation instructions.

* [[Windows installation]]
** [[Installing Moodle on SmarterASP.NET]]
* [[Unix or Linux Installation]]
* [[Mac Installation]]
* [[Amazon EC2 Cloud Services Installation]]

== See also ==
* [http://www.slideshare.net/gb2048/my-own-moodle Slideshare presentation by Gareth Barnard on installing a local installation of Moodle] and accompanying [https://drive.google.com/folderview?id=0B17B0rYH2zERU21sQnVweUZCUFk&usp=sharing help guides]
* [http://moodle.org/mod/forum/discuss.php?d=182086 New Video Tutorial- How to Install Moodle on Shared Hosting via cPanel (Not Fantastico)]
* [http://moodle.org/mod/forum/discuss.php?d=199542 Video Tutorial - Install Moodle on a Virtual Box from scratch]

[[es:Instalaci%C3%B3n_de_moodle]]
[[de:Installation von Moodle]]
[[fr:Installation de Moodle]]
[[ja:Moodleのインストール]]

Talk:Installing Moodle

2015-11-30T13:55:23Z

Mrverrall:

<blockquote>"'''Oracle and MSSQL are fully supported''' (but may never have been tested for optional plugins) but documentation and '''support is limited'''".</blockquote> (emphasis added)
How can they be fully supported if support is limited? Perhaps there should be a better explanation of what is meant by "support" here?

[[User:Mark Johnson|Mark Johnson]] 16:48, 23 January 2012 (WST)

Fair point - improved I hope --[[User:Howard Miller|Howard Miller]] 22:52, 21 March 2012 (WST)

----

<blockquote>It is strongly recommended to use ACL when your server supports it ... <code>chmod -R +a ...</code></blockquote>

The docs suggest a specific syntax for setting ACLs that only seems to work on OSX instead of Linux systems which is what the Requirements section suggestions this document is primarily focused on.

The ACL given also seems to directly against the security advice also given on that page. <code>It is vital that the files are not writable by the web server user</code>

--[[User:Chris Francy|Chris Francy]] ([[User talk:Chris Francy|talk]]) 04:51, 1 February 2014 (WST)

I agree and think that talk of ACL's it confusing and unnecessary in the standard install docs.

--[[User:Paul Verrall|Paul Verrall]] ([[User talk:Paul Verrall|talk]]) 21:55, 30 November 2015 (AWST)
----

Please see Create an empty database section and check if --<blockquote> Oracle (known issues, not fully supported)
</blockquote> -- is correct or which Moodle version affects. When you go and see release_notes for Software requirements, don't say anything about issues. --[[User:Carina Martinez 2|Carina Martinez 2]] ([[User talk:Carina Martinez 2|talk]]) 00:43, 20 November 2014 (AWST)

----

Installing Moodle

2015-11-30T13:39:20Z

Mrverrall: /* Set up your server */ Mention slash args and hopefully generally improve this section.

{{Template:Installing Moodle}}
''This page explains how to install Moodle. If you are an expert and/or in a hurry try [[Installation Quickstart]].''

If you just want to try Moodle on a standalone machine there are 'one-click' installers for Windows (see [[Complete install packages for Windows]]) and for OSX (see [[Complete Install Packages for Mac OS X]]) or [[ install on OS X]]. These are unsuitable for production servers.

== Requirements ==

Moodle is primarily developed in Linux using [[Apache]], [[PostgreSQL]]/[[MySQL]]/[[MariaDB]] and [[PHP]] (sometimes known as the LAMP platform). Typically this is also how Moodle is run, although there are other options as long as the software requirements of the [{{Release notes}} release] are met.

If you are installing Moodle in a Windows server, note that from php5.5 onwards, you will also need to have the Visual C++ Redistributable for Visual Studio 2012 installed from:
http://www.microsoft.com/en-us/download/details.aspx?id=30679 Visual C++] ( x86 or x64)

The basic requirements for Moodle are as follows:

=== Hardware ===
* Disk space: 200MB for the Moodle code, plus as much as you need to store content. 5GB is probably a realistic minimum.
* Processor: 1GHz (min), 2GHz dual core or more recommended.
* Memory: 512MB (min), 1GB or more is recommended.

All the above requirements will vary depending on specific hardware and software combinations as well as the type of use and load; busy sites may well require additional resources. Further guidance can be found under [[Performance_recommendations|performance recommendations]].

=== Software ===

See the [{{Release notes}} release notes] in the dev docs for software requirements.

== Set up your server ==

Depending the use case a Moodle server may be anything from a Desktop PC (e.g. for testing and evaluating) to a rackmounted or [[Server cluster|clustered]] solution. As mentioned above there are lots of possibilities for installing the basic server software, some links and pointers are at [[Installing AMP]], [[Internet_Information_Services|IIS]], [[Nginx]].

It will help hugely, regardless of your deployment choices, if time is taken to understand how to configure the different parts of your software stack (HTTP daemon, database, PHP etc) e.g. it is important that the HTTP daemon is configured to support [[Using slash arguments| slash arguments]].

If a hosting provider in being used ensure that all Moodle [{{Release notes}}#Server_requirements requirments] (such as PHP version) are met by the hosting platform, otherwise all the core configuration should be done. I will be helpful to become familiar with how to change setting within the hosting providers platform (e.g. PHP file upload maximums) as the options and tools provided can vary a huge amount between then.

== Download and copy files into place ==

'''IMPORTANT: While there are now a number of places you can get the Moodle code, you are strongly advised to obtain Moodle from moodle.org. If you run into problems it will be a great deal easier to support you.'''

You have two options:
* Download your required version from http://moodle.org/downloads and unzip/unpack...
* '''OR''' Pull the code from the Git repository (recommended for developers and also makes upgrading very simple):
<pre>
$ git clone --depth=1 -b MOODLE_30_STABLE git://git.moodle.org/moodle.git
</pre>
--depth=1 for shallow cloning (only) latest revision

--single-branch option to limit cloning to a single branch, this fetches the Moodle 3.0 Stable branch (latest weekly build). For a fuller discussion see [[Git for Administrators]].

Either of the above should result in a directory called '''moodle''', containing a number of files and folders.

You can either place the whole folder in your web server documents directory, in which case the site will be located at '''<nowiki>http://yourwebserver.com/moodle</nowiki>''', or you can copy all the contents straight into the main web server documents directory, in which case the site will be simply '''<nowiki>http://yourwebserver.com</nowiki>'''. See the documentation for your system and/or web server if you are unsure.

:''Tip:'' If you are downloading Moodle to your local computer and then uploading it to your hosted web site, if possible upload the compressed file and decompress at the remote end (check your 'file manager'). Failing that, watch FTP progress carefully for errors or missed files.

* '''Secure the Moodle files:''' It is vital that the files are not writeable by the web server user. For example, on Unix/Linux (as root):
<pre>
# chown -R root /path/to/moodle
# chmod -R 0755 /path/to/moodle
# find /path/to/moodle -type f -exec chmod 0644 {} \;
</pre>
(files are owned by the administrator/superuser and are only writeable by them - readable by everyone else)

The third command finds all the regular files and executes the chmod command 0644 on them.

If you want to use the built-in plugin installer you need to make the directory writable by web server user. It is strongly recommended to use ACL when your server supports it, for example if your Apache server uses account www-data:

<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodle
</pre>

The effect of the previous command is to allow the Apache user account (www-data in this case) to access and change files within the moodle site. Many people would consider this a brave move for a new site admin to implement. In a new moodle you can safely leave this out. A default Ubuntu install does not have the +a option for the chmod command anyway. The +a attribute is an ACL (Access Control List) facility which allows you to set per user access for individual files. For example, OSX has this by default.

== Create an empty database ==

Next create a new, empty database for your installation. You need to find and make a note of following information for use during the final installation stage:
* '''dbhost''' - the database server hostname. Probably ''localhost'' if the database and web server are the same machine, otherwise the name of the database server
* '''dbname''' - the database name. Whatever you called it, e.g. ''moodle''
* '''dbuser''' - the username for the database. Whatever you assigned, e.g. ''moodleuser'' - do not use the root/superuser account. Create a proper account with the minimum permissions needed.
* '''dbpass''' - the password for the above user

If your site is hosted you should find a web-based administration page for databases as part of the control panel (or ask your administrator). For everyone else or for detailed instructions, see the page for your chosen database server:
* [[PostgreSQL]]
* [[MariaDB]] (known issues - see MDL-45233)
* [[MySQL]] (known issues - see MDL-45233)
* [[MSSQL]]
* [[Oracle]] (known issues, not fully supported - see MDL-41310)

== Create the (''moodledata'') data directory ==

Moodle requires a directory to store all of its files (all your site's uploaded files, temporary data, cache, session data etc.). The web server needs to be able to write to this directory. On larger systems consider how much free space you are going to use when allocating this directory.

Due to the way Moodle caches data you may have performance issues if you use relatively slow storage (e.g. NFS) for this directory. Read the [[Performance_recommendations]] carefully and consider using (e.g.) memcached for [[Caching]].

'''IMPORTANT:''' This directory must '''NOT''' be accessible directly via the web. This would be a serious security hole. Do not try to place it inside your web root or inside your Moodle program files directory. Moodle will not install. It can go anywhere else convenient.

Here is an example (Unix/Linux) of creating the directory and setting the permissions for '''anyone''' on the server to write here. This is only appropriate for Moodle servers that are not shared. Discuss this with your server administrator for better permissions that just allow the web server user to access these files.

<pre>
# mkdir /path/to/moodledata
# chmod 0777 /path/to/moodledata
</pre>

If your server supports ACL it is recommended to set following permissions, for example if your Apache server uses account www-data:
<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>
If you are planning to execute PHP scripts from the command line you should set the same permissions for the current user:
<pre>
$ sudo chmod -R +a "`whoami` allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>

==== Securing moodledata in a web directory ====

If you are using a hosted site and you have no option but to place 'moodledata' in a web accessible directory. You may be able to secure it by creating an .htaccess file in the 'moodledata' directory. This does not work on all systems - see your host/administrator. Create a file called .htaccess containing only the following lines:
<pre>
order deny,allow
deny from all
</pre>

== Start Moodle install ==
It's now time to run the installer to create the database tables and configure your new site. The recommended method is to use the command line installer. If you cannot do this for any reason (e.g. on a Windows server) the web based installer is still available.

=== Command line installer ===

It's best to run the command line as your system's web user. You need to know what that is - see your system's documentation (e.g. Ubuntu/Debian is 'www-data', Centos is 'apache')

* Example of using the command-line (as root - substitute 'www-data' for your web user):
<pre>
# chown www-data /path/to/moodle
# cd /path/to/moodle/admin/cli
# sudo -u www-data /usr/bin/php install.php
# chown -R root /path/to/moodle
</pre>
The chowns allow the script to write a new config.php file. More information about the options can be found using
<pre>
# php install.php --help
</pre>

You will be asked for other settings that have not been discussed on this page - if unsure just accept the defaults. For a full discussion see [[Administration via command line]]

=== Web based installer ===
To run the web installer script, just go to your Moodle's main URL using a web browser.

The installation process will take you through a number of pages. You should be asked to confirm the copyright, see the database tables being created, supply administrator account details and supply the site details. The database creation can take some time - please be patient. You should eventually end up at the Moodle front page with an invitation to create a new course.

It is very likely that you will be asked to download the new config.php file and upload it to your Moodle installation - just follow the on-screen instructions.

==Final configuration==

=== Settings within Moodle ===
There are a number of options within the Moodle Site Administration screens (accessible from the 'Site administration' tab in the 'Administration' block. Here are a few of the more important ones that you will probably want to check:
* ''Administration > Site administration > Plugins > Message Outputs > Email'': Set your smtp server and authentication if required (so your Moodle site can send emails). The support contact for your site is also set on this page.
* ''Administration > Site administration > Server > System paths'': Set the paths to du, dot and aspell binaries.
* ''Administration > Site administration > Server > HTTP'': If you are behind a firewall you may need to set your proxy credentials in the 'Web proxy' section.
* ''Administration > Site administration > Location > Update timezones'': Run this to make sure your timezone information is up to date. (more info [[Location]])
** [http://php.net/manual/en/timezones.php Set server's local timezone] inside <tt>php.ini</tt> (should probably be inside <tt>/etc/php.ini</tt> or <tt>/etc/php.d/date.ini</tt>, depending on the underline OS):
**: <code ini>[Date]
; Defines the default timezone used by the date functions
date.timezone = "YOUR LOCAL TIMEZONE"</code>

=== Remaining tasks ===

* '''Configure Cron''': Moodle's background tasks (e.g. sending out forum emails and performing course backups) are performed by a script which you can set to execute at specific times of the day. This is known as a cron script. Please refer to the [[Cron|Cron instructions]].
* '''Set up backups''': See [[Site backup]] and [[Automated course backup]].
* '''Check mail works''': [[Add a new user|Create a test user]] with a valid email address and [[message|send them a message]]. Do they receive an email copy of the message? If not, check the settings in ''Settings > Site administration > Plugins > Message outputs > Email''. Don't be tempted to skip this step (clue: email is used to recover lost passwords, including the administrator password when you forget it!)
* '''Secure your Moodle site''': Read the [[Security recommendations]].
*'''Increasing the maximum upload size''' See [[Installation FAQ]] Maximum upload file size - how to change it?

=== Installation is complete :) ===

* Create a new course: You can now [[Adding a new course|create a new course]] and have a play ;-)

=== If something goes wrong... ===

Here are some things you should try...

* Check the [[Installation FAQ]]
* Check your file permissions carefully. Can your web server read (but not write) the Moodle program files? Can your web server read and write your Moodle data directory?
* Check your database permissions. Have you set up your database user with the correct rights and permissions for your configuration (especially if the web server and database server are different machines)?
* Create your [[Configuration file]] (config.php) by hand. Copy config-dist.php (in the root of the Moodle program directory) to config.php, edit it and set your database/site options there. Installation will continue from the right place.
* Once you have a config.php (see previous tip) you can edit it to turn on debugging (in section 8). This may give you extra information to help track down a problem. If you have access, check your web server error log(s).
* Re-check your php.ini / .htaccess settings. Are they appropriate (e.g. memory_limit), did you edit the correct php.ini / .htaccess file and (if required) did you re-start the web server after making changes?
* Did you include any non-core (optional) plugins, themes or other code before starting the installation script? If so, remove it and try again (it may be broken or incompatible).
* Explain your problem in the [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]. '''PLEASE''' list your software versions; explain what you did, what happened and what error messages you saw (if any); explain what you tried. There is no such thing as 'nothing', even a blank page is something!

== Platform specific instructions ==

'''Note:''' Much of this information is provided by the community. It may not have been checked and may be out of date. Please read in conjunction with the above installation instructions.

* [[Windows installation]]
** [[Installing Moodle on SmarterASP.NET]]
* [[Unix or Linux Installation]]
* [[Mac Installation]]
* [[Amazon EC2 Cloud Services Installation]]

== See also ==
* [http://www.slideshare.net/gb2048/my-own-moodle Slideshare presentation by Gareth Barnard on installing a local installation of Moodle] and accompanying [https://drive.google.com/folderview?id=0B17B0rYH2zERU21sQnVweUZCUFk&usp=sharing help guides]
* [http://moodle.org/mod/forum/discuss.php?d=182086 New Video Tutorial- How to Install Moodle on Shared Hosting via cPanel (Not Fantastico)]
* [http://moodle.org/mod/forum/discuss.php?d=199542 Video Tutorial - Install Moodle on a Virtual Box from scratch]

[[es:Instalaci%C3%B3n_de_moodle]]
[[de:Installation von Moodle]]
[[fr:Installation de Moodle]]
[[ja:Moodleのインストール]]

Installing Moodle

2015-11-30T12:54:31Z

Mrverrall: /* Requirements */

{{Template:Installing Moodle}}
''This page explains how to install Moodle. If you are an expert and/or in a hurry try [[Installation Quickstart]].''

If you just want to try Moodle on a standalone machine there are 'one-click' installers for Windows (see [[Complete install packages for Windows]]) and for OSX (see [[Complete Install Packages for Mac OS X]]) or [[ install on OS X]]. These are unsuitable for production servers.

== Requirements ==

Moodle is primarily developed in Linux using [[Apache]], [[PostgreSQL]]/[[MySQL]]/[[MariaDB]] and [[PHP]] (sometimes known as the LAMP platform). Typically this is also how Moodle is run, although there are other options as long as the software requirements of the [{{Release notes}} release] are met.

If you are installing Moodle in a Windows server, note that from php5.5 onwards, you will also need to have the Visual C++ Redistributable for Visual Studio 2012 installed from:
http://www.microsoft.com/en-us/download/details.aspx?id=30679 Visual C++] ( x86 or x64)

The basic requirements for Moodle are as follows:

=== Hardware ===
* Disk space: 200MB for the Moodle code, plus as much as you need to store content. 5GB is probably a realistic minimum.
* Processor: 1GHz (min), 2GHz dual core or more recommended.
* Memory: 512MB (min), 1GB or more is recommended.

All the above requirements will vary depending on specific hardware and software combinations as well as the type of use and load; busy sites may well require additional resources. Further guidance can be found under [[Performance_recommendations|performance recommendations]].

=== Software ===

See the [{{Release notes}} release notes] in the dev docs for software requirements.

== Set up your server ==

...or desktop computer, if you are just evaluating Moodle. There are lots of possibilities for installing the basic server software depending on your particular choices. Some links and pointers are at [[Installing AMP]], [[Internet_Information_Services|IIS]], [[Nginx]]

If you are using a hosted server all this should be done for you. However, (especially on shared hosting) make sure you understand or find out how to change PHP settings (e.g. file upload maximums). This can vary a huge amount from host to host. You also need to verify that your webhost supports the required php version for the Moodle installation you are installing.

== Download and copy files into place ==

'''IMPORTANT: While there are now a number of places you can get the Moodle code, you are strongly advised to obtain Moodle from moodle.org. If you run into problems it will be a great deal easier to support you.'''

You have two options:
* Download your required version from http://moodle.org/downloads and unzip/unpack...
* '''OR''' Pull the code from the Git repository (recommended for developers and also makes upgrading very simple):
<pre>
$ git clone --depth=1 -b MOODLE_30_STABLE git://git.moodle.org/moodle.git
</pre>
--depth=1 for shallow cloning (only) latest revision

--single-branch option to limit cloning to a single branch, this fetches the Moodle 3.0 Stable branch (latest weekly build). For a fuller discussion see [[Git for Administrators]].

Either of the above should result in a directory called '''moodle''', containing a number of files and folders.

You can either place the whole folder in your web server documents directory, in which case the site will be located at '''<nowiki>http://yourwebserver.com/moodle</nowiki>''', or you can copy all the contents straight into the main web server documents directory, in which case the site will be simply '''<nowiki>http://yourwebserver.com</nowiki>'''. See the documentation for your system and/or web server if you are unsure.

:''Tip:'' If you are downloading Moodle to your local computer and then uploading it to your hosted web site, if possible upload the compressed file and decompress at the remote end (check your 'file manager'). Failing that, watch FTP progress carefully for errors or missed files.

* '''Secure the Moodle files:''' It is vital that the files are not writeable by the web server user. For example, on Unix/Linux (as root):
<pre>
# chown -R root /path/to/moodle
# chmod -R 0755 /path/to/moodle
# find /path/to/moodle -type f -exec chmod 0644 {} \;
</pre>
(files are owned by the administrator/superuser and are only writeable by them - readable by everyone else)

The third command finds all the regular files and executes the chmod command 0644 on them.

If you want to use the built-in plugin installer you need to make the directory writable by web server user. It is strongly recommended to use ACL when your server supports it, for example if your Apache server uses account www-data:

<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodle
</pre>

The effect of the previous command is to allow the Apache user account (www-data in this case) to access and change files within the moodle site. Many people would consider this a brave move for a new site admin to implement. In a new moodle you can safely leave this out. A default Ubuntu install does not have the +a option for the chmod command anyway. The +a attribute is an ACL (Access Control List) facility which allows you to set per user access for individual files. For example, OSX has this by default.

== Create an empty database ==

Next create a new, empty database for your installation. You need to find and make a note of following information for use during the final installation stage:
* '''dbhost''' - the database server hostname. Probably ''localhost'' if the database and web server are the same machine, otherwise the name of the database server
* '''dbname''' - the database name. Whatever you called it, e.g. ''moodle''
* '''dbuser''' - the username for the database. Whatever you assigned, e.g. ''moodleuser'' - do not use the root/superuser account. Create a proper account with the minimum permissions needed.
* '''dbpass''' - the password for the above user

If your site is hosted you should find a web-based administration page for databases as part of the control panel (or ask your administrator). For everyone else or for detailed instructions, see the page for your chosen database server:
* [[PostgreSQL]]
* [[MariaDB]] (known issues - see MDL-45233)
* [[MySQL]] (known issues - see MDL-45233)
* [[MSSQL]]
* [[Oracle]] (known issues, not fully supported - see MDL-41310)

== Create the (''moodledata'') data directory ==

Moodle requires a directory to store all of its files (all your site's uploaded files, temporary data, cache, session data etc.). The web server needs to be able to write to this directory. On larger systems consider how much free space you are going to use when allocating this directory.

Due to the way Moodle caches data you may have performance issues if you use relatively slow storage (e.g. NFS) for this directory. Read the [[Performance_recommendations]] carefully and consider using (e.g.) memcached for [[Caching]].

'''IMPORTANT:''' This directory must '''NOT''' be accessible directly via the web. This would be a serious security hole. Do not try to place it inside your web root or inside your Moodle program files directory. Moodle will not install. It can go anywhere else convenient.

Here is an example (Unix/Linux) of creating the directory and setting the permissions for '''anyone''' on the server to write here. This is only appropriate for Moodle servers that are not shared. Discuss this with your server administrator for better permissions that just allow the web server user to access these files.

<pre>
# mkdir /path/to/moodledata
# chmod 0777 /path/to/moodledata
</pre>

If your server supports ACL it is recommended to set following permissions, for example if your Apache server uses account www-data:
<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>
If you are planning to execute PHP scripts from the command line you should set the same permissions for the current user:
<pre>
$ sudo chmod -R +a "`whoami` allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>

==== Securing moodledata in a web directory ====

If you are using a hosted site and you have no option but to place 'moodledata' in a web accessible directory. You may be able to secure it by creating an .htaccess file in the 'moodledata' directory. This does not work on all systems - see your host/administrator. Create a file called .htaccess containing only the following lines:
<pre>
order deny,allow
deny from all
</pre>

== Start Moodle install ==
It's now time to run the installer to create the database tables and configure your new site. The recommended method is to use the command line installer. If you cannot do this for any reason (e.g. on a Windows server) the web based installer is still available.

=== Command line installer ===

It's best to run the command line as your system's web user. You need to know what that is - see your system's documentation (e.g. Ubuntu/Debian is 'www-data', Centos is 'apache')

* Example of using the command-line (as root - substitute 'www-data' for your web user):
<pre>
# chown www-data /path/to/moodle
# cd /path/to/moodle/admin/cli
# sudo -u www-data /usr/bin/php install.php
# chown -R root /path/to/moodle
</pre>
The chowns allow the script to write a new config.php file. More information about the options can be found using
<pre>
# php install.php --help
</pre>

You will be asked for other settings that have not been discussed on this page - if unsure just accept the defaults. For a full discussion see [[Administration via command line]]

=== Web based installer ===
To run the web installer script, just go to your Moodle's main URL using a web browser.

The installation process will take you through a number of pages. You should be asked to confirm the copyright, see the database tables being created, supply administrator account details and supply the site details. The database creation can take some time - please be patient. You should eventually end up at the Moodle front page with an invitation to create a new course.

It is very likely that you will be asked to download the new config.php file and upload it to your Moodle installation - just follow the on-screen instructions.

==Final configuration==

=== Settings within Moodle ===
There are a number of options within the Moodle Site Administration screens (accessible from the 'Site administration' tab in the 'Administration' block. Here are a few of the more important ones that you will probably want to check:
* ''Administration > Site administration > Plugins > Message Outputs > Email'': Set your smtp server and authentication if required (so your Moodle site can send emails). The support contact for your site is also set on this page.
* ''Administration > Site administration > Server > System paths'': Set the paths to du, dot and aspell binaries.
* ''Administration > Site administration > Server > HTTP'': If you are behind a firewall you may need to set your proxy credentials in the 'Web proxy' section.
* ''Administration > Site administration > Location > Update timezones'': Run this to make sure your timezone information is up to date. (more info [[Location]])
** [http://php.net/manual/en/timezones.php Set server's local timezone] inside <tt>php.ini</tt> (should probably be inside <tt>/etc/php.ini</tt> or <tt>/etc/php.d/date.ini</tt>, depending on the underline OS):
**: <code ini>[Date]
; Defines the default timezone used by the date functions
date.timezone = "YOUR LOCAL TIMEZONE"</code>

=== Remaining tasks ===

* '''Configure Cron''': Moodle's background tasks (e.g. sending out forum emails and performing course backups) are performed by a script which you can set to execute at specific times of the day. This is known as a cron script. Please refer to the [[Cron|Cron instructions]].
* '''Set up backups''': See [[Site backup]] and [[Automated course backup]].
* '''Check mail works''': [[Add a new user|Create a test user]] with a valid email address and [[message|send them a message]]. Do they receive an email copy of the message? If not, check the settings in ''Settings > Site administration > Plugins > Message outputs > Email''. Don't be tempted to skip this step (clue: email is used to recover lost passwords, including the administrator password when you forget it!)
* '''Secure your Moodle site''': Read the [[Security recommendations]].
*'''Increasing the maximum upload size''' See [[Installation FAQ]] Maximum upload file size - how to change it?

=== Installation is complete :) ===

* Create a new course: You can now [[Adding a new course|create a new course]] and have a play ;-)

=== If something goes wrong... ===

Here are some things you should try...

* Check the [[Installation FAQ]]
* Check your file permissions carefully. Can your web server read (but not write) the Moodle program files? Can your web server read and write your Moodle data directory?
* Check your database permissions. Have you set up your database user with the correct rights and permissions for your configuration (especially if the web server and database server are different machines)?
* Create your [[Configuration file]] (config.php) by hand. Copy config-dist.php (in the root of the Moodle program directory) to config.php, edit it and set your database/site options there. Installation will continue from the right place.
* Once you have a config.php (see previous tip) you can edit it to turn on debugging (in section 8). This may give you extra information to help track down a problem. If you have access, check your web server error log(s).
* Re-check your php.ini / .htaccess settings. Are they appropriate (e.g. memory_limit), did you edit the correct php.ini / .htaccess file and (if required) did you re-start the web server after making changes?
* Did you include any non-core (optional) plugins, themes or other code before starting the installation script? If so, remove it and try again (it may be broken or incompatible).
* Explain your problem in the [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]. '''PLEASE''' list your software versions; explain what you did, what happened and what error messages you saw (if any); explain what you tried. There is no such thing as 'nothing', even a blank page is something!

== Platform specific instructions ==

'''Note:''' Much of this information is provided by the community. It may not have been checked and may be out of date. Please read in conjunction with the above installation instructions.

* [[Windows installation]]
** [[Installing Moodle on SmarterASP.NET]]
* [[Unix or Linux Installation]]
* [[Mac Installation]]
* [[Amazon EC2 Cloud Services Installation]]

== See also ==
* [http://www.slideshare.net/gb2048/my-own-moodle Slideshare presentation by Gareth Barnard on installing a local installation of Moodle] and accompanying [https://drive.google.com/folderview?id=0B17B0rYH2zERU21sQnVweUZCUFk&usp=sharing help guides]
* [http://moodle.org/mod/forum/discuss.php?d=182086 New Video Tutorial- How to Install Moodle on Shared Hosting via cPanel (Not Fantastico)]
* [http://moodle.org/mod/forum/discuss.php?d=199542 Video Tutorial - Install Moodle on a Virtual Box from scratch]

[[es:Instalaci%C3%B3n_de_moodle]]
[[de:Installation von Moodle]]
[[fr:Installation de Moodle]]
[[ja:Moodleのインストール]]

Installing Moodle

2015-11-30T11:24:38Z

Mrverrall: Undo revision 121333 by Tsala (talk). Already updated to remove superfluous text and ambiguity for 3.0. The restored text adds no information not already stated in this section.

{{Template:Installing Moodle}}
''This page explains how to install Moodle. If you are an expert and/or in a hurry try [[Installation Quickstart]].''

If you just want to try Moodle on a standalone machine there are 'one-click' installers for Windows (see [[Complete install packages for Windows]]) and for OSX (see [[Complete Install Packages for Mac OS X]]) or [[ install on OS X]]. These are unsuitable for production servers.

== Requirements ==

Moodle is primarily developed in Linux using [[Apache]], [[PostgreSQL]]/[[MySQL]]/[[MariaDB]] and [[PHP]] (also sometimes known as the LAMP platform). There are other options - see the Software section that follows:

If you are installing Moodle in a Windows server, note that from php5.5 onwards, you will also need to have the Visual C++ Redistributable for Visual Studio 2012 installed from:
http://www.microsoft.com/en-us/download/details.aspx?id=30679 Visual C++] ( x86 or x64)

The basic requirements for Moodle are as follows:

=== Hardware ===
* Disk space: 200MB for the Moodle code, plus as much as you need to store content. 5GB is probably a realistic minimum.
* Processor: 1GHz (min), 2GHz dual core or more recommended.
* Memory: 512MB (min), 1GB or more is recommended.

All the above requirements will vary depending on specific hardware and software combinations as well as the type of use and load; busy sites may well require additional resources. Further guidance can be found under [[Performance_recommendations|performance recommendations]].

=== Software ===

See the [{{Release notes}} release notes] in the dev docs for software requirements.

== Set up your server ==

...or desktop computer, if you are just evaluating Moodle. There are lots of possibilities for installing the basic server software depending on your particular choices. Some links and pointers are at [[Installing AMP]], [[Internet_Information_Services|IIS]], [[Nginx]]

If you are using a hosted server all this should be done for you. However, (especially on shared hosting) make sure you understand or find out how to change PHP settings (e.g. file upload maximums). This can vary a huge amount from host to host. You also need to verify that your webhost supports the required php version for the Moodle installation you are installing.

== Download and copy files into place ==

'''IMPORTANT: While there are now a number of places you can get the Moodle code, you are strongly advised to obtain Moodle from moodle.org. If you run into problems it will be a great deal easier to support you.'''

You have two options:
* Download your required version from http://moodle.org/downloads and unzip/unpack...
* '''OR''' Pull the code from the Git repository (recommended for developers and also makes upgrading very simple):
<pre>
$ git clone --depth=1 -b MOODLE_30_STABLE git://git.moodle.org/moodle.git
</pre>
--depth=1 for shallow cloning (only) latest revision

--single-branch option to limit cloning to a single branch, this fetches the Moodle 3.0 Stable branch (latest weekly build). For a fuller discussion see [[Git for Administrators]].

Either of the above should result in a directory called '''moodle''', containing a number of files and folders.

You can either place the whole folder in your web server documents directory, in which case the site will be located at '''<nowiki>http://yourwebserver.com/moodle</nowiki>''', or you can copy all the contents straight into the main web server documents directory, in which case the site will be simply '''<nowiki>http://yourwebserver.com</nowiki>'''. See the documentation for your system and/or web server if you are unsure.

:''Tip:'' If you are downloading Moodle to your local computer and then uploading it to your hosted web site, if possible upload the compressed file and decompress at the remote end (check your 'file manager'). Failing that, watch FTP progress carefully for errors or missed files.

* '''Secure the Moodle files:''' It is vital that the files are not writeable by the web server user. For example, on Unix/Linux (as root):
<pre>
# chown -R root /path/to/moodle
# chmod -R 0755 /path/to/moodle
# find /path/to/moodle -type f -exec chmod 0644 {} \;
</pre>
(files are owned by the administrator/superuser and are only writeable by them - readable by everyone else)

The third command finds all the regular files and executes the chmod command 0644 on them.

If you want to use the built-in plugin installer you need to make the directory writable by web server user. It is strongly recommended to use ACL when your server supports it, for example if your Apache server uses account www-data:

<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodle
</pre>

The effect of the previous command is to allow the Apache user account (www-data in this case) to access and change files within the moodle site. Many people would consider this a brave move for a new site admin to implement. In a new moodle you can safely leave this out. A default Ubuntu install does not have the +a option for the chmod command anyway. The +a attribute is an ACL (Access Control List) facility which allows you to set per user access for individual files. For example, OSX has this by default.

== Create an empty database ==

Next create a new, empty database for your installation. You need to find and make a note of following information for use during the final installation stage:
* '''dbhost''' - the database server hostname. Probably ''localhost'' if the database and web server are the same machine, otherwise the name of the database server
* '''dbname''' - the database name. Whatever you called it, e.g. ''moodle''
* '''dbuser''' - the username for the database. Whatever you assigned, e.g. ''moodleuser'' - do not use the root/superuser account. Create a proper account with the minimum permissions needed.
* '''dbpass''' - the password for the above user

If your site is hosted you should find a web-based administration page for databases as part of the control panel (or ask your administrator). For everyone else or for detailed instructions, see the page for your chosen database server:
* [[PostgreSQL]]
* [[MariaDB]] (known issues - see MDL-45233)
* [[MySQL]] (known issues - see MDL-45233)
* [[MSSQL]]
* [[Oracle]] (known issues, not fully supported - see MDL-41310)

== Create the (''moodledata'') data directory ==

Moodle requires a directory to store all of its files (all your site's uploaded files, temporary data, cache, session data etc.). The web server needs to be able to write to this directory. On larger systems consider how much free space you are going to use when allocating this directory.

Due to the way Moodle caches data you may have performance issues if you use relatively slow storage (e.g. NFS) for this directory. Read the [[Performance_recommendations]] carefully and consider using (e.g.) memcached for [[Caching]].

'''IMPORTANT:''' This directory must '''NOT''' be accessible directly via the web. This would be a serious security hole. Do not try to place it inside your web root or inside your Moodle program files directory. Moodle will not install. It can go anywhere else convenient.

Here is an example (Unix/Linux) of creating the directory and setting the permissions for '''anyone''' on the server to write here. This is only appropriate for Moodle servers that are not shared. Discuss this with your server administrator for better permissions that just allow the web server user to access these files.

<pre>
# mkdir /path/to/moodledata
# chmod 0777 /path/to/moodledata
</pre>

If your server supports ACL it is recommended to set following permissions, for example if your Apache server uses account www-data:
<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>
If you are planning to execute PHP scripts from the command line you should set the same permissions for the current user:
<pre>
$ sudo chmod -R +a "`whoami` allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>

==== Securing moodledata in a web directory ====

If you are using a hosted site and you have no option but to place 'moodledata' in a web accessible directory. You may be able to secure it by creating an .htaccess file in the 'moodledata' directory. This does not work on all systems - see your host/administrator. Create a file called .htaccess containing only the following lines:
<pre>
order deny,allow
deny from all
</pre>

== Start Moodle install ==
It's now time to run the installer to create the database tables and configure your new site. The recommended method is to use the command line installer. If you cannot do this for any reason (e.g. on a Windows server) the web based installer is still available.

=== Command line installer ===

It's best to run the command line as your system's web user. You need to know what that is - see your system's documentation (e.g. Ubuntu/Debian is 'www-data', Centos is 'apache')

* Example of using the command-line (as root - substitute 'www-data' for your web user):
<pre>
# chown www-data /path/to/moodle
# cd /path/to/moodle/admin/cli
# sudo -u www-data /usr/bin/php install.php
# chown -R root /path/to/moodle
</pre>
The chowns allow the script to write a new config.php file. More information about the options can be found using
<pre>
# php install.php --help
</pre>

You will be asked for other settings that have not been discussed on this page - if unsure just accept the defaults. For a full discussion see [[Administration via command line]]

=== Web based installer ===
To run the web installer script, just go to your Moodle's main URL using a web browser.

The installation process will take you through a number of pages. You should be asked to confirm the copyright, see the database tables being created, supply administrator account details and supply the site details. The database creation can take some time - please be patient. You should eventually end up at the Moodle front page with an invitation to create a new course.

It is very likely that you will be asked to download the new config.php file and upload it to your Moodle installation - just follow the on-screen instructions.

==Final configuration==

=== Settings within Moodle ===
There are a number of options within the Moodle Site Administration screens (accessible from the 'Site administration' tab in the 'Administration' block. Here are a few of the more important ones that you will probably want to check:
* ''Administration > Site administration > Plugins > Message Outputs > Email'': Set your smtp server and authentication if required (so your Moodle site can send emails). The support contact for your site is also set on this page.
* ''Administration > Site administration > Server > System paths'': Set the paths to du, dot and aspell binaries.
* ''Administration > Site administration > Server > HTTP'': If you are behind a firewall you may need to set your proxy credentials in the 'Web proxy' section.
* ''Administration > Site administration > Location > Update timezones'': Run this to make sure your timezone information is up to date. (more info [[Location]])
** [http://php.net/manual/en/timezones.php Set server's local timezone] inside <tt>php.ini</tt> (should probably be inside <tt>/etc/php.ini</tt> or <tt>/etc/php.d/date.ini</tt>, depending on the underline OS):
**: <code ini>[Date]
; Defines the default timezone used by the date functions
date.timezone = "YOUR LOCAL TIMEZONE"</code>

=== Remaining tasks ===

* '''Configure Cron''': Moodle's background tasks (e.g. sending out forum emails and performing course backups) are performed by a script which you can set to execute at specific times of the day. This is known as a cron script. Please refer to the [[Cron|Cron instructions]].
* '''Set up backups''': See [[Site backup]] and [[Automated course backup]].
* '''Check mail works''': [[Add a new user|Create a test user]] with a valid email address and [[message|send them a message]]. Do they receive an email copy of the message? If not, check the settings in ''Settings > Site administration > Plugins > Message outputs > Email''. Don't be tempted to skip this step (clue: email is used to recover lost passwords, including the administrator password when you forget it!)
* '''Secure your Moodle site''': Read the [[Security recommendations]].
*'''Increasing the maximum upload size''' See [[Installation FAQ]] Maximum upload file size - how to change it?

=== Installation is complete :) ===

* Create a new course: You can now [[Adding a new course|create a new course]] and have a play ;-)

=== If something goes wrong... ===

Here are some things you should try...

* Check the [[Installation FAQ]]
* Check your file permissions carefully. Can your web server read (but not write) the Moodle program files? Can your web server read and write your Moodle data directory?
* Check your database permissions. Have you set up your database user with the correct rights and permissions for your configuration (especially if the web server and database server are different machines)?
* Create your [[Configuration file]] (config.php) by hand. Copy config-dist.php (in the root of the Moodle program directory) to config.php, edit it and set your database/site options there. Installation will continue from the right place.
* Once you have a config.php (see previous tip) you can edit it to turn on debugging (in section 8). This may give you extra information to help track down a problem. If you have access, check your web server error log(s).
* Re-check your php.ini / .htaccess settings. Are they appropriate (e.g. memory_limit), did you edit the correct php.ini / .htaccess file and (if required) did you re-start the web server after making changes?
* Did you include any non-core (optional) plugins, themes or other code before starting the installation script? If so, remove it and try again (it may be broken or incompatible).
* Explain your problem in the [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]. '''PLEASE''' list your software versions; explain what you did, what happened and what error messages you saw (if any); explain what you tried. There is no such thing as 'nothing', even a blank page is something!

== Platform specific instructions ==

'''Note:''' Much of this information is provided by the community. It may not have been checked and may be out of date. Please read in conjunction with the above installation instructions.

* [[Windows installation]]
** [[Installing Moodle on SmarterASP.NET]]
* [[Unix or Linux Installation]]
* [[Mac Installation]]
* [[Amazon EC2 Cloud Services Installation]]

== See also ==
* [http://www.slideshare.net/gb2048/my-own-moodle Slideshare presentation by Gareth Barnard on installing a local installation of Moodle] and accompanying [https://drive.google.com/folderview?id=0B17B0rYH2zERU21sQnVweUZCUFk&usp=sharing help guides]
* [http://moodle.org/mod/forum/discuss.php?d=182086 New Video Tutorial- How to Install Moodle on Shared Hosting via cPanel (Not Fantastico)]
* [http://moodle.org/mod/forum/discuss.php?d=199542 Video Tutorial - Install Moodle on a Virtual Box from scratch]

[[es:Instalaci%C3%B3n_de_moodle]]
[[de:Installation von Moodle]]
[[fr:Installation de Moodle]]
[[ja:Moodleのインストール]]

OPcache

2015-11-18T11:20:20Z

Mrverrall: /* Configuration */ Revised value for max_accelerated_files for 3.0 and more concise explanation of it's use.

{{Environment}}

The standard OPcache extension is strongly recommended; since Moodle 2.6, it is the only solution officially supported by PHP developers. The benefits are increased performance and significantly lower memory usage. However, opcode caching extensions (including OPcache, eAccelerator and APC) aren't compatible with servers configured to use some common types of high-security PHP handlers such as suPHP (the default on WHM / cPanel Linux servers).

==Installation==

The OPcache extension is distributed as part of PHP 5.5.0 and later. It is available also for older stable PHP releases from PECL under the original name ZendOPcache.

'''NOTE: If you are running PHP 5.3 or 5.4 you can safely ignore the Environment Check message about OpCache. Nonetheless, [https://moodle.org/mod/forum/discuss.php?d=245885 it might be useful] to upgrade Operating System/PHP and get to 5.5 or newer; as there have been all sorts of problems described on PHP 5.2 and 5.3, and upgrading PHP turned out to be the easier solution. '''

==Configuration==

PHP.ini settings:

<code ini>
[opcache]
opcache.enable = 1
opcache.memory_consumption = 128
opcache.max_accelerated_files = 8000
opcache.revalidate_freq = 60

; Required for Moodle
opcache.use_cwd = 1
opcache.validate_timestamps = 1
opcache.save_comments = 1
opcache.enable_file_override = 0

; If something does not work in Moodle
;opcache.revalidate_path = 1 ; May fix problems with include paths
;opcache.mmap_base = 0x20000000 ; (Windows only) fix OPcache crashes with event id 487

; Experimental for Moodle 2.6 and later
;opcache.fast_shutdown = 1
;opcache.enable_cli = 1 ; Speeds up CLI cron
;opcache.load_comments = 0 ; May lower memory use, might not be compatible with add-ons and other apps.
</code>

When using non-Windows platforms, you have to use the ''zend_extension'' configuration to load the OPcache extension into PHP by adding to php.ini.
<code ini>
zend_extension=/full/path/to/opcache.so
</code>

When using IIS you will need PHP 5.5 and you will need to add the extension for opcache under the ''ExtensionList'' section of the php.ini file. For PHP 5.3 and 5.4 you can download the binaries separately from [http://windows.php.net/downloads/pecl/releases/opcache] and you will also need to enter full absolute path to the module dll in php.ini.

<code ini>
[ExtensionList]
...
zend_extension=php_opcache.dll
</code>

; max_accelerated_files
From: [http://php.net/manual/en/opcache.configuration.php#ini.opcache.max-accelerated-files php.net max-accelerated-files]
*''The maximum number of keys (and therefore scripts) in the OPcache hash table. The actual value used will be the first number in the set of prime numbers { 223, 463, 983, 1979, 3907, 7963, 16229, 32531, 65407, 130987 } that is bigger than the configured value. Only numbers between 200 and 100000 are allowed.''

As Moodle 3.0 contains over 8000 php files it is recommended above that opcache.max_accelerated_files should be set to 8000 to accommodate this (16229 will actually be used as per the explanation above).

If many additional plugins are installed so that your total PHP files exceed 16229 then the next most suitable value for max_accelerated_files should be used.

==See also==
* [http://pecl.php.net/package/ZendOpcache PECL ZendOPcache]
* [http://windows.php.net/downloads/pecl/releases/opcache/ Windows builds for PHP 5.3-5.4]

Forum discussions:
* [https://moodle.org/mod/forum/discuss.php?d=244133 OPcache: Memory Usage = 100% (is this good or bad?)]
* [https://moodle.org/mod/forum/discuss.php?d=245885 OPCode cache]

[[Category:Environment]]
[[Category:Installation]]
[[Category:Performance]]

[[es:OPcache]]

Installing Moodle

2015-11-05T09:13:15Z

Mrverrall: /* Hardware */ Pointless statement and already covered in the final paragraph.

{{Template:Installing Moodle}}
''This page explains how to install Moodle. If you are an expert and/or in a hurry try [[Installation Quickstart]].''

If you just want to try Moodle on a standalone machine there are 'one-click' installers for Windows (see [[Complete install packages for Windows]]) and for OSX (see [[Complete Install Packages for Mac OS X]]) or [[ install on OS X]]. These are unsuitable for production servers.

== Requirements ==

Moodle is primarily developed in Linux using [[Apache]], [[PostgreSQL]]/[[MySQL]]/[[MariaDB]] and [[PHP]] (also sometimes known as the LAMP platform). If in doubt, this is the safest combination (if for no other reason than being the most common). There are other options - see the Software section that follows:

If you are installing Moodle in a Windows server, note that from php5.5 onwards, you will also need to have the Visual C++ Redistributable for Visual Studio 2012 installed from:
http://www.microsoft.com/en-us/download/details.aspx?id=30679 Visual C++] ( x86 or x64)

The basic requirements for Moodle are as follows:

=== Hardware ===
* Disk space: 200MB for the Moodle code, plus as much as you need to store content. 5GB is probably a realistic minimum.
* Processor: 1GHz (min), 2GHz dual core or more recommended.
* Memory: 512MB (min), 1GB or more is recommended.

All the above requirements will vary depending on specific hardware and software combinations as well as the type of use and load; busy sites may well require additional resources. Further guidance can be found under [[Performance_recommendations|performance recommendations]].

=== Software ===

See the [{{Release notes}} release notes] in the dev docs for software requirements.

== Set up your server ==

...or desktop computer, if you are just evaluating Moodle. There are lots of possibilities for installing the basic server software depending on your particular choices. Some links and pointers are at [[Installing AMP]], [[Internet_Information_Services|IIS]], [[Nginx]]

If you are using a hosted server all this should be done for you. However, (especially on shared hosting) make sure you understand or find out how to change PHP settings (e.g. file upload maximums). This can vary a huge amount from host to host. You also need to verify that your webhost supports the required php version for the Moodle installation you are installing.

== Download and copy files into place ==

'''IMPORTANT: While there are now a number of places you can get the Moodle code, you are strongly advised to obtain Moodle from moodle.org. If you run into problems it will be a great deal easier to support you.'''

You have two options:
* Download your required version from http://moodle.org/downloads and unzip/unpack...
* '''OR''' Pull the code from the Git repository (recommended for developers and also makes upgrading very simple):
<pre>
$ git clone --depth=1 -b MOODLE_30_STABLE git://git.moodle.org/moodle.git
</pre>
--depth=1 for shallow cloning (only) latest revision

--single-branch option to limit cloning to a single branch, this fetches the Moodle 3.0 Stable branch (latest weekly build). For a fuller discussion see [[Git for Administrators]].

Either of the above should result in a directory called '''moodle''', containing a number of files and folders.

You can either place the whole folder in your web server documents directory, in which case the site will be located at '''<nowiki>http://yourwebserver.com/moodle</nowiki>''', or you can copy all the contents straight into the main web server documents directory, in which case the site will be simply '''<nowiki>http://yourwebserver.com</nowiki>'''. See the documentation for your system and/or web server if you are unsure.

:''Tip:'' If you are downloading Moodle to your local computer and then uploading it to your hosted web site, if possible upload the compressed file and decompress at the remote end (check your 'file manager'). Failing that, watch FTP progress carefully for errors or missed files.

* '''Secure the Moodle files:''' It is vital that the files are not writeable by the web server user. For example, on Unix/Linux (as root):
<pre>
# chown -R root /path/to/moodle
# chmod -R 0755 /path/to/moodle
# find /path/to/moodle -type f -exec chmod 0644 {} \;
</pre>
(files are owned by the administrator/superuser and are only writeable by them - readable by everyone else)

The third command finds all the regular files and executes the chmod command 0644 on them.

If you want to use the built-in plugin installer you need to make the directory writable by web server user. It is strongly recommended to use ACL when your server supports it, for example if your Apache server uses account www-data:

<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodle
</pre>

The effect of the previous command is to allow the Apache user account (www-data in this case) to access and change files within the moodle site. Many people would consider this a brave move for a new site admin to implement. In a new moodle you can safely leave this out. A default Ubuntu install does not have the +a option for the chmod command anyway. The +a attribute is an ACL (Access Control List) facility which allows you to set per user access for individual files. For example, OSX has this by default.

== Create an empty database ==

Next create a new, empty database for your installation. You need to find and make a note of following information for use during the final installation stage:
* '''dbhost''' - the database server hostname. Probably ''localhost'' if the database and web server are the same machine, otherwise the name of the database server
* '''dbname''' - the database name. Whatever you called it, e.g. ''moodle''
* '''dbuser''' - the username for the database. Whatever you assigned, e.g. ''moodleuser'' - do not use the root/superuser account. Create a proper account with the minimum permissions needed.
* '''dbpass''' - the password for the above user

If your site is hosted you should find a web-based administration page for databases as part of the control panel (or ask your administrator). For everyone else or for detailed instructions, see the page for your chosen database server:
* [[PostgreSQL]]
* [[MariaDB]]
* [[MySQL]]
* [[MSSQL]]
* [[Oracle]] (known issues, not fully supported - see MDL-41310)

== Create the (''moodledata'') data directory ==

Moodle requires a directory to store all of its files (all your site's uploaded files, temporary data, cache, session data etc.). The web server needs to be able to write to this directory. On larger systems consider how much free space you are going to use when allocating this directory.

Due to the way Moodle caches data you may have performance issues if you use relatively slow storage (e.g. NFS) for this directory. Read the [[Performance_recommendations]] carefully and consider using (e.g.) memcached for [[Caching]].

'''IMPORTANT:''' This directory must '''NOT''' be accessible directly via the web. This would be a serious security hole. Do not try to place it inside your web root or inside your Moodle program files directory. Moodle will not install. It can go anywhere else convenient.

Here is an example (Unix/Linux) of creating the directory and setting the permissions for '''anyone''' on the server to write here. This is only appropriate for Moodle servers that are not shared. Discuss this with your server administrator for better permissions that just allow the web server user to access these files.

<pre>
# mkdir /path/to/moodledata
# chmod 0777 /path/to/moodledata
</pre>

If your server supports ACL it is recommended to set following permissions, for example if your Apache server uses account www-data:
<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>
If you are planning to execute PHP scripts from the command line you should set the same permissions for the current user:
<pre>
$ sudo chmod -R +a "`whoami` allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>

==== Securing moodledata in a web directory ====

If you are using a hosted site and you have no option but to place 'moodledata' in a web accessible directory. You may be able to secure it by creating an .htaccess file in the 'moodledata' directory. This does not work on all systems - see your host/administrator. Create a file called .htaccess containing only the following lines:
<pre>
order deny,allow
deny from all
</pre>

== Start Moodle install ==
It's now time to run the installer to create the database tables and configure your new site. The recommended method is to use the command line installer. If you cannot do this for any reason (e.g. on a Windows server) the web based installer is still available.

=== Command line installer ===

It's best to run the command line as your system's web user. You need to know what that is - see your system's documentation (e.g. Ubuntu/Debian is 'www-data', Centos is 'apache')

* Example of using the command-line (as root - substitute 'www-data' for your web user):
<pre>
# chown www-data /path/to/moodle
# cd /path/to/moodle/admin/cli
# sudo -u www-data /usr/bin/php install.php
# chown -R root /path/to/moodle
</pre>
The chowns allow the script to write a new config.php file. More information about the options can be found using
<pre>
# php install.php --help
</pre>

You will be asked for other settings that have not been discussed on this page - if unsure just accept the defaults. For a full discussion see [[Administration via command line]]

=== Web based installer ===
To run the web installer script, just go to your Moodle's main URL using a web browser.

The installation process will take you through a number of pages. You should be asked to confirm the copyright, see the database tables being created, supply administrator account details and supply the site details. The database creation can take some time - please be patient. You should eventually end up at the Moodle front page with an invitation to create a new course.

It is very likely that you will be asked to download the new config.php file and upload it to your Moodle installation - just follow the on-screen instructions.

==Final configuration==

=== Settings within Moodle ===
There are a number of options within the Moodle Site Administration screens (accessible from the 'Site administration' tab in the 'Administration' block. Here are a few of the more important ones that you will probably want to check:
* ''Administration > Site administration > Plugins > Message Outputs > Email'': Set your smtp server and authentication if required (so your Moodle site can send emails). The support contact for your site is also set on this page.
* ''Administration > Site administration > Server > System paths'': Set the paths to du, dot and aspell binaries.
* ''Administration > Site administration > Server > HTTP'': If you are behind a firewall you may need to set your proxy credentials in the 'Web proxy' section.
* ''Administration > Site administration > Location > Update timezones'': Run this to make sure your timezone information is up to date. (more info [[Location]])
** [http://php.net/manual/en/timezones.php Set server's local timezone] inside <tt>php.ini</tt> (should probably be inside <tt>/etc/php.ini</tt> or <tt>/etc/php.d/date.ini</tt>, depending on the underline OS):
**: <code ini>[Date]
; Defines the default timezone used by the date functions
date.timezone = "YOUR LOCAL TIMEZONE"</code>

=== Remaining tasks ===

* '''Configure Cron''': Moodle's background tasks (e.g. sending out forum emails and performing course backups) are performed by a script which you can set to execute at specific times of the day. This is known as a cron script. Please refer to the [[Cron|Cron instructions]].
* '''Set up backups''': See [[Site backup]] and [[Automated course backup]].
* '''Check mail works''': [[Add a new user|Create a test user]] with a valid email address and [[message|send them a message]]. Do they receive an email copy of the message? If not, check the settings in ''Settings > Site administration > Plugins > Message outputs > Email''. Don't be tempted to skip this step (clue: email is used to recover lost passwords, including the administrator password when you forget it!)
* '''Secure your Moodle site''': Read the [[Security recommendations]].
*'''Increasing the maximum upload size''' See [[Installation FAQ]] Maximum upload file size - how to change it?

=== Installation is complete :) ===

* Create a new course: You can now [[Adding a new course|create a new course]] and have a play ;-)

=== If something goes wrong... ===

Here are some things you should try...

* Check the [[Installation FAQ]]
* Check your file permissions carefully. Can your web server read (but not write) the Moodle program files? Can your web server read and write your Moodle data directory?
* Check your database permissions. Have you set up your database user with the correct rights and permissions for your configuration (especially if the web server and database server are different machines)?
* Create your [[Configuration file]] (config.php) by hand. Copy config-dist.php (in the root of the Moodle program directory) to config.php, edit it and set your database/site options there. Installation will continue from the right place.
* Once you have a config.php (see previous tip) you can edit it to turn on debugging (in section 8). This may give you extra information to help track down a problem. If you have access, check your web server error log(s).
* Re-check your php.ini / .htaccess settings. Are they appropriate (e.g. memory_limit), did you edit the correct php.ini / .htaccess file and (if required) did you re-start the web server after making changes?
* Did you include any non-core (optional) plugins, themes or other code before starting the installation script? If so, remove it and try again (it may be broken or incompatible).
* Explain your problem in the [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]. '''PLEASE''' list your software versions; explain what you did, what happened and what error messages you saw (if any); explain what you tried. There is no such thing as 'nothing', even a blank page is something!

== Platform specific instructions ==

'''Note:''' Much of this information is provided by the community. It may not have been checked and may be out of date. Please read in conjunction with the above installation instructions.

* [[Windows installation]]
** [[Installing Moodle on SmarterASP.NET]]
* [[Unix or Linux Installation]]
* [[Mac Installation]]
* [[Amazon EC2 Cloud Services Installation]]

== See also ==
* [http://www.slideshare.net/gb2048/my-own-moodle Slideshare presentation by Gareth Barnard on installing a local installation of Moodle] and accompanying [https://drive.google.com/folderview?id=0B17B0rYH2zERU21sQnVweUZCUFk&usp=sharing help guides]
* [http://moodle.org/mod/forum/discuss.php?d=182086 New Video Tutorial- How to Install Moodle on Shared Hosting via cPanel (Not Fantastico)]
* [http://moodle.org/mod/forum/discuss.php?d=199542 Video Tutorial - Install Moodle on a Virtual Box from scratch]

[[es:Instalaci%C3%B3n_de_moodle]]
[[de:Installation von Moodle]]
[[fr:Installation de Moodle]]
[[ja:Moodleのインストール]]

Installing Moodle

2015-11-05T09:12:06Z

Mrverrall: /* Hardware */ Not sure that backups need to be mentioned at all here as it is not a 'Requirement' to install Moodle.

{{Template:Installing Moodle}}
''This page explains how to install Moodle. If you are an expert and/or in a hurry try [[Installation Quickstart]].''

If you just want to try Moodle on a standalone machine there are 'one-click' installers for Windows (see [[Complete install packages for Windows]]) and for OSX (see [[Complete Install Packages for Mac OS X]]) or [[ install on OS X]]. These are unsuitable for production servers.

== Requirements ==

Moodle is primarily developed in Linux using [[Apache]], [[PostgreSQL]]/[[MySQL]]/[[MariaDB]] and [[PHP]] (also sometimes known as the LAMP platform). If in doubt, this is the safest combination (if for no other reason than being the most common). There are other options - see the Software section that follows:

If you are installing Moodle in a Windows server, note that from php5.5 onwards, you will also need to have the Visual C++ Redistributable for Visual Studio 2012 installed from:
http://www.microsoft.com/en-us/download/details.aspx?id=30679 Visual C++] ( x86 or x64)

The basic requirements for Moodle are as follows:

=== Hardware ===
* Disk space: 200MB for the Moodle code, plus as much as you need to store content. 5GB is probably a realistic minimum.
* Processor: 1GHz (min), 2GHz dual core recommended. These settings may vary according to the resources used.
* Memory: 512MB (min), 1GB or more is recommended.

All the above requirements will vary depending on specific hardware and software combinations as well as the type of use and load; busy sites may well require additional resources. Further guidance can be found under [[Performance_recommendations|performance recommendations]].

=== Software ===

See the [{{Release notes}} release notes] in the dev docs for software requirements.

== Set up your server ==

...or desktop computer, if you are just evaluating Moodle. There are lots of possibilities for installing the basic server software depending on your particular choices. Some links and pointers are at [[Installing AMP]], [[Internet_Information_Services|IIS]], [[Nginx]]

If you are using a hosted server all this should be done for you. However, (especially on shared hosting) make sure you understand or find out how to change PHP settings (e.g. file upload maximums). This can vary a huge amount from host to host. You also need to verify that your webhost supports the required php version for the Moodle installation you are installing.

== Download and copy files into place ==

'''IMPORTANT: While there are now a number of places you can get the Moodle code, you are strongly advised to obtain Moodle from moodle.org. If you run into problems it will be a great deal easier to support you.'''

You have two options:
* Download your required version from http://moodle.org/downloads and unzip/unpack...
* '''OR''' Pull the code from the Git repository (recommended for developers and also makes upgrading very simple):
<pre>
$ git clone --depth=1 -b MOODLE_30_STABLE git://git.moodle.org/moodle.git
</pre>
--depth=1 for shallow cloning (only) latest revision

--single-branch option to limit cloning to a single branch, this fetches the Moodle 3.0 Stable branch (latest weekly build). For a fuller discussion see [[Git for Administrators]].

Either of the above should result in a directory called '''moodle''', containing a number of files and folders.

You can either place the whole folder in your web server documents directory, in which case the site will be located at '''<nowiki>http://yourwebserver.com/moodle</nowiki>''', or you can copy all the contents straight into the main web server documents directory, in which case the site will be simply '''<nowiki>http://yourwebserver.com</nowiki>'''. See the documentation for your system and/or web server if you are unsure.

:''Tip:'' If you are downloading Moodle to your local computer and then uploading it to your hosted web site, if possible upload the compressed file and decompress at the remote end (check your 'file manager'). Failing that, watch FTP progress carefully for errors or missed files.

* '''Secure the Moodle files:''' It is vital that the files are not writeable by the web server user. For example, on Unix/Linux (as root):
<pre>
# chown -R root /path/to/moodle
# chmod -R 0755 /path/to/moodle
# find /path/to/moodle -type f -exec chmod 0644 {} \;
</pre>
(files are owned by the administrator/superuser and are only writeable by them - readable by everyone else)

The third command finds all the regular files and executes the chmod command 0644 on them.

If you want to use the built-in plugin installer you need to make the directory writable by web server user. It is strongly recommended to use ACL when your server supports it, for example if your Apache server uses account www-data:

<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodle
</pre>

The effect of the previous command is to allow the Apache user account (www-data in this case) to access and change files within the moodle site. Many people would consider this a brave move for a new site admin to implement. In a new moodle you can safely leave this out. A default Ubuntu install does not have the +a option for the chmod command anyway. The +a attribute is an ACL (Access Control List) facility which allows you to set per user access for individual files. For example, OSX has this by default.

== Create an empty database ==

Next create a new, empty database for your installation. You need to find and make a note of following information for use during the final installation stage:
* '''dbhost''' - the database server hostname. Probably ''localhost'' if the database and web server are the same machine, otherwise the name of the database server
* '''dbname''' - the database name. Whatever you called it, e.g. ''moodle''
* '''dbuser''' - the username for the database. Whatever you assigned, e.g. ''moodleuser'' - do not use the root/superuser account. Create a proper account with the minimum permissions needed.
* '''dbpass''' - the password for the above user

If your site is hosted you should find a web-based administration page for databases as part of the control panel (or ask your administrator). For everyone else or for detailed instructions, see the page for your chosen database server:
* [[PostgreSQL]]
* [[MariaDB]]
* [[MySQL]]
* [[MSSQL]]
* [[Oracle]] (known issues, not fully supported - see MDL-41310)

== Create the (''moodledata'') data directory ==

Moodle requires a directory to store all of its files (all your site's uploaded files, temporary data, cache, session data etc.). The web server needs to be able to write to this directory. On larger systems consider how much free space you are going to use when allocating this directory.

Due to the way Moodle caches data you may have performance issues if you use relatively slow storage (e.g. NFS) for this directory. Read the [[Performance_recommendations]] carefully and consider using (e.g.) memcached for [[Caching]].

'''IMPORTANT:''' This directory must '''NOT''' be accessible directly via the web. This would be a serious security hole. Do not try to place it inside your web root or inside your Moodle program files directory. Moodle will not install. It can go anywhere else convenient.

Here is an example (Unix/Linux) of creating the directory and setting the permissions for '''anyone''' on the server to write here. This is only appropriate for Moodle servers that are not shared. Discuss this with your server administrator for better permissions that just allow the web server user to access these files.

<pre>
# mkdir /path/to/moodledata
# chmod 0777 /path/to/moodledata
</pre>

If your server supports ACL it is recommended to set following permissions, for example if your Apache server uses account www-data:
<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>
If you are planning to execute PHP scripts from the command line you should set the same permissions for the current user:
<pre>
$ sudo chmod -R +a "`whoami` allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>

==== Securing moodledata in a web directory ====

If you are using a hosted site and you have no option but to place 'moodledata' in a web accessible directory. You may be able to secure it by creating an .htaccess file in the 'moodledata' directory. This does not work on all systems - see your host/administrator. Create a file called .htaccess containing only the following lines:
<pre>
order deny,allow
deny from all
</pre>

== Start Moodle install ==
It's now time to run the installer to create the database tables and configure your new site. The recommended method is to use the command line installer. If you cannot do this for any reason (e.g. on a Windows server) the web based installer is still available.

=== Command line installer ===

It's best to run the command line as your system's web user. You need to know what that is - see your system's documentation (e.g. Ubuntu/Debian is 'www-data', Centos is 'apache')

* Example of using the command-line (as root - substitute 'www-data' for your web user):
<pre>
# chown www-data /path/to/moodle
# cd /path/to/moodle/admin/cli
# sudo -u www-data /usr/bin/php install.php
# chown -R root /path/to/moodle
</pre>
The chowns allow the script to write a new config.php file. More information about the options can be found using
<pre>
# php install.php --help
</pre>

You will be asked for other settings that have not been discussed on this page - if unsure just accept the defaults. For a full discussion see [[Administration via command line]]

=== Web based installer ===
To run the web installer script, just go to your Moodle's main URL using a web browser.

The installation process will take you through a number of pages. You should be asked to confirm the copyright, see the database tables being created, supply administrator account details and supply the site details. The database creation can take some time - please be patient. You should eventually end up at the Moodle front page with an invitation to create a new course.

It is very likely that you will be asked to download the new config.php file and upload it to your Moodle installation - just follow the on-screen instructions.

==Final configuration==

=== Settings within Moodle ===
There are a number of options within the Moodle Site Administration screens (accessible from the 'Site administration' tab in the 'Administration' block. Here are a few of the more important ones that you will probably want to check:
* ''Administration > Site administration > Plugins > Message Outputs > Email'': Set your smtp server and authentication if required (so your Moodle site can send emails). The support contact for your site is also set on this page.
* ''Administration > Site administration > Server > System paths'': Set the paths to du, dot and aspell binaries.
* ''Administration > Site administration > Server > HTTP'': If you are behind a firewall you may need to set your proxy credentials in the 'Web proxy' section.
* ''Administration > Site administration > Location > Update timezones'': Run this to make sure your timezone information is up to date. (more info [[Location]])
** [http://php.net/manual/en/timezones.php Set server's local timezone] inside <tt>php.ini</tt> (should probably be inside <tt>/etc/php.ini</tt> or <tt>/etc/php.d/date.ini</tt>, depending on the underline OS):
**: <code ini>[Date]
; Defines the default timezone used by the date functions
date.timezone = "YOUR LOCAL TIMEZONE"</code>

=== Remaining tasks ===

* '''Configure Cron''': Moodle's background tasks (e.g. sending out forum emails and performing course backups) are performed by a script which you can set to execute at specific times of the day. This is known as a cron script. Please refer to the [[Cron|Cron instructions]].
* '''Set up backups''': See [[Site backup]] and [[Automated course backup]].
* '''Check mail works''': [[Add a new user|Create a test user]] with a valid email address and [[message|send them a message]]. Do they receive an email copy of the message? If not, check the settings in ''Settings > Site administration > Plugins > Message outputs > Email''. Don't be tempted to skip this step (clue: email is used to recover lost passwords, including the administrator password when you forget it!)
* '''Secure your Moodle site''': Read the [[Security recommendations]].
*'''Increasing the maximum upload size''' See [[Installation FAQ]] Maximum upload file size - how to change it?

=== Installation is complete :) ===

* Create a new course: You can now [[Adding a new course|create a new course]] and have a play ;-)

=== If something goes wrong... ===

Here are some things you should try...

* Check the [[Installation FAQ]]
* Check your file permissions carefully. Can your web server read (but not write) the Moodle program files? Can your web server read and write your Moodle data directory?
* Check your database permissions. Have you set up your database user with the correct rights and permissions for your configuration (especially if the web server and database server are different machines)?
* Create your [[Configuration file]] (config.php) by hand. Copy config-dist.php (in the root of the Moodle program directory) to config.php, edit it and set your database/site options there. Installation will continue from the right place.
* Once you have a config.php (see previous tip) you can edit it to turn on debugging (in section 8). This may give you extra information to help track down a problem. If you have access, check your web server error log(s).
* Re-check your php.ini / .htaccess settings. Are they appropriate (e.g. memory_limit), did you edit the correct php.ini / .htaccess file and (if required) did you re-start the web server after making changes?
* Did you include any non-core (optional) plugins, themes or other code before starting the installation script? If so, remove it and try again (it may be broken or incompatible).
* Explain your problem in the [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]. '''PLEASE''' list your software versions; explain what you did, what happened and what error messages you saw (if any); explain what you tried. There is no such thing as 'nothing', even a blank page is something!

== Platform specific instructions ==

'''Note:''' Much of this information is provided by the community. It may not have been checked and may be out of date. Please read in conjunction with the above installation instructions.

* [[Windows installation]]
** [[Installing Moodle on SmarterASP.NET]]
* [[Unix or Linux Installation]]
* [[Mac Installation]]
* [[Amazon EC2 Cloud Services Installation]]

== See also ==
* [http://www.slideshare.net/gb2048/my-own-moodle Slideshare presentation by Gareth Barnard on installing a local installation of Moodle] and accompanying [https://drive.google.com/folderview?id=0B17B0rYH2zERU21sQnVweUZCUFk&usp=sharing help guides]
* [http://moodle.org/mod/forum/discuss.php?d=182086 New Video Tutorial- How to Install Moodle on Shared Hosting via cPanel (Not Fantastico)]
* [http://moodle.org/mod/forum/discuss.php?d=199542 Video Tutorial - Install Moodle on a Virtual Box from scratch]

[[es:Instalaci%C3%B3n_de_moodle]]
[[de:Installation von Moodle]]
[[fr:Installation de Moodle]]
[[ja:Moodleのインストール]]

Installing Moodle

2015-11-05T08:36:03Z

Mrverrall: /* Hardware */ 512MB is a much more realistic minimum memory requirement.

{{Template:Installing Moodle}}
''This page explains how to install Moodle. If you are an expert and/or in a hurry try [[Installation Quickstart]].''

If you just want to try Moodle on a standalone machine there are 'one-click' installers for Windows (see [[Complete install packages for Windows]]) and for OSX (see [[Complete Install Packages for Mac OS X]]) or [[ install on OS X]]. These are unsuitable for production servers.

== Requirements ==

Moodle is primarily developed in Linux using [[Apache]], [[PostgreSQL]]/[[MySQL]]/[[MariaDB]] and [[PHP]] (also sometimes known as the LAMP platform). If in doubt, this is the safest combination (if for no other reason than being the most common). There are other options - see the Software section that follows:

If you are installing Moodle in a Windows server, note that from php5.5 onwards, you will also need to have the Visual C++ Redistributable for Visual Studio 2012 installed from:
http://www.microsoft.com/en-us/download/details.aspx?id=30679 Visual C++] ( x86 or x64)

The basic requirements for Moodle are as follows:

=== Hardware ===
* Disk space: 200MB for the Moodle code, plus as much as you need to store content. 5GB is probably a realistic minimum.
* Processor: 1GHz (min), 2GHz dual core recommended. These settings may vary according to the resources used.
* Backups: at least the same again (at a remote location preferably) as above to keep backups of your site.
* Memory: 512MB (min), 1GB or more is recommended.

All the above requirements will vary depending on specific hardware and software combinations as well as the type of use and load; busy sites may well require additional resources. Further guidance can be found under [[Performance_recommendations|performance recommendations]].

=== Software ===

See the [{{Release notes}} release notes] in the dev docs for software requirements.

== Set up your server ==

...or desktop computer, if you are just evaluating Moodle. There are lots of possibilities for installing the basic server software depending on your particular choices. Some links and pointers are at [[Installing AMP]], [[Internet_Information_Services|IIS]], [[Nginx]]

If you are using a hosted server all this should be done for you. However, (especially on shared hosting) make sure you understand or find out how to change PHP settings (e.g. file upload maximums). This can vary a huge amount from host to host. You also need to verify that your webhost supports the required php version for the Moodle installation you are installing.

== Download and copy files into place ==

'''IMPORTANT: While there are now a number of places you can get the Moodle code, you are strongly advised to obtain Moodle from moodle.org. If you run into problems it will be a great deal easier to support you.'''

You have two options:
* Download your required version from http://moodle.org/downloads and unzip/unpack...
* '''OR''' Pull the code from the Git repository (recommended for developers and also makes upgrading very simple):
<pre>
$ git clone --depth=1 -b MOODLE_30_STABLE git://git.moodle.org/moodle.git
</pre>
--depth=1 for shallow cloning (only) latest revision

--single-branch option to limit cloning to a single branch, this fetches the Moodle 3.0 Stable branch (latest weekly build). For a fuller discussion see [[Git for Administrators]].

Either of the above should result in a directory called '''moodle''', containing a number of files and folders.

You can either place the whole folder in your web server documents directory, in which case the site will be located at '''<nowiki>http://yourwebserver.com/moodle</nowiki>''', or you can copy all the contents straight into the main web server documents directory, in which case the site will be simply '''<nowiki>http://yourwebserver.com</nowiki>'''. See the documentation for your system and/or web server if you are unsure.

:''Tip:'' If you are downloading Moodle to your local computer and then uploading it to your hosted web site, if possible upload the compressed file and decompress at the remote end (check your 'file manager'). Failing that, watch FTP progress carefully for errors or missed files.

* '''Secure the Moodle files:''' It is vital that the files are not writeable by the web server user. For example, on Unix/Linux (as root):
<pre>
# chown -R root /path/to/moodle
# chmod -R 0755 /path/to/moodle
# find /path/to/moodle -type f -exec chmod 0644 {} \;
</pre>
(files are owned by the administrator/superuser and are only writeable by them - readable by everyone else)

The third command finds all the regular files and executes the chmod command 0644 on them.

If you want to use the built-in plugin installer you need to make the directory writable by web server user. It is strongly recommended to use ACL when your server supports it, for example if your Apache server uses account www-data:

<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodle
</pre>

The effect of the previous command is to allow the Apache user account (www-data in this case) to access and change files within the moodle site. Many people would consider this a brave move for a new site admin to implement. In a new moodle you can safely leave this out. A default Ubuntu install does not have the +a option for the chmod command anyway. The +a attribute is an ACL (Access Control List) facility which allows you to set per user access for individual files. For example, OSX has this by default.

== Create an empty database ==

Next create a new, empty database for your installation. You need to find and make a note of following information for use during the final installation stage:
* '''dbhost''' - the database server hostname. Probably ''localhost'' if the database and web server are the same machine, otherwise the name of the database server
* '''dbname''' - the database name. Whatever you called it, e.g. ''moodle''
* '''dbuser''' - the username for the database. Whatever you assigned, e.g. ''moodleuser'' - do not use the root/superuser account. Create a proper account with the minimum permissions needed.
* '''dbpass''' - the password for the above user

If your site is hosted you should find a web-based administration page for databases as part of the control panel (or ask your administrator). For everyone else or for detailed instructions, see the page for your chosen database server:
* [[PostgreSQL]]
* [[MariaDB]]
* [[MySQL]]
* [[MSSQL]]
* [[Oracle]] (known issues, not fully supported - see MDL-41310)

== Create the (''moodledata'') data directory ==

Moodle requires a directory to store all of its files (all your site's uploaded files, temporary data, cache, session data etc.). The web server needs to be able to write to this directory. On larger systems consider how much free space you are going to use when allocating this directory.

Due to the way Moodle caches data you may have performance issues if you use relatively slow storage (e.g. NFS) for this directory. Read the [[Performance_recommendations]] carefully and consider using (e.g.) memcached for [[Caching]].

'''IMPORTANT:''' This directory must '''NOT''' be accessible directly via the web. This would be a serious security hole. Do not try to place it inside your web root or inside your Moodle program files directory. Moodle will not install. It can go anywhere else convenient.

Here is an example (Unix/Linux) of creating the directory and setting the permissions for '''anyone''' on the server to write here. This is only appropriate for Moodle servers that are not shared. Discuss this with your server administrator for better permissions that just allow the web server user to access these files.

<pre>
# mkdir /path/to/moodledata
# chmod 0777 /path/to/moodledata
</pre>

If your server supports ACL it is recommended to set following permissions, for example if your Apache server uses account www-data:
<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>
If you are planning to execute PHP scripts from the command line you should set the same permissions for the current user:
<pre>
$ sudo chmod -R +a "`whoami` allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>

==== Securing moodledata in a web directory ====

If you are using a hosted site and you have no option but to place 'moodledata' in a web accessible directory. You may be able to secure it by creating an .htaccess file in the 'moodledata' directory. This does not work on all systems - see your host/administrator. Create a file called .htaccess containing only the following lines:
<pre>
order deny,allow
deny from all
</pre>

== Start Moodle install ==
It's now time to run the installer to create the database tables and configure your new site. The recommended method is to use the command line installer. If you cannot do this for any reason (e.g. on a Windows server) the web based installer is still available.

=== Command line installer ===

It's best to run the command line as your system's web user. You need to know what that is - see your system's documentation (e.g. Ubuntu/Debian is 'www-data', Centos is 'apache')

* Example of using the command-line (as root - substitute 'www-data' for your web user):
<pre>
# chown www-data /path/to/moodle
# cd /path/to/moodle/admin/cli
# sudo -u www-data /usr/bin/php install.php
# chown -R root /path/to/moodle
</pre>
The chowns allow the script to write a new config.php file. More information about the options can be found using
<pre>
# php install.php --help
</pre>

You will be asked for other settings that have not been discussed on this page - if unsure just accept the defaults. For a full discussion see [[Administration via command line]]

=== Web based installer ===
To run the web installer script, just go to your Moodle's main URL using a web browser.

The installation process will take you through a number of pages. You should be asked to confirm the copyright, see the database tables being created, supply administrator account details and supply the site details. The database creation can take some time - please be patient. You should eventually end up at the Moodle front page with an invitation to create a new course.

It is very likely that you will be asked to download the new config.php file and upload it to your Moodle installation - just follow the on-screen instructions.

==Final configuration==

=== Settings within Moodle ===
There are a number of options within the Moodle Site Administration screens (accessible from the 'Site administration' tab in the 'Administration' block. Here are a few of the more important ones that you will probably want to check:
* ''Administration > Site administration > Plugins > Message Outputs > Email'': Set your smtp server and authentication if required (so your Moodle site can send emails). The support contact for your site is also set on this page.
* ''Administration > Site administration > Server > System paths'': Set the paths to du, dot and aspell binaries.
* ''Administration > Site administration > Server > HTTP'': If you are behind a firewall you may need to set your proxy credentials in the 'Web proxy' section.
* ''Administration > Site administration > Location > Update timezones'': Run this to make sure your timezone information is up to date. (more info [[Location]])
** [http://php.net/manual/en/timezones.php Set server's local timezone] inside <tt>php.ini</tt> (should probably be inside <tt>/etc/php.ini</tt> or <tt>/etc/php.d/date.ini</tt>, depending on the underline OS):
**: <code ini>[Date]
; Defines the default timezone used by the date functions
date.timezone = "YOUR LOCAL TIMEZONE"</code>

=== Remaining tasks ===

* '''Configure Cron''': Moodle's background tasks (e.g. sending out forum emails and performing course backups) are performed by a script which you can set to execute at specific times of the day. This is known as a cron script. Please refer to the [[Cron|Cron instructions]].
* '''Set up backups''': See [[Site backup]] and [[Automated course backup]].
* '''Check mail works''': [[Add a new user|Create a test user]] with a valid email address and [[message|send them a message]]. Do they receive an email copy of the message? If not, check the settings in ''Settings > Site administration > Plugins > Message outputs > Email''. Don't be tempted to skip this step (clue: email is used to recover lost passwords, including the administrator password when you forget it!)
* '''Secure your Moodle site''': Read the [[Security recommendations]].
*'''Increasing the maximum upload size''' See [[Installation FAQ]] Maximum upload file size - how to change it?

=== Installation is complete :) ===

* Create a new course: You can now [[Adding a new course|create a new course]] and have a play ;-)

=== If something goes wrong... ===

Here are some things you should try...

* Check the [[Installation FAQ]]
* Check your file permissions carefully. Can your web server read (but not write) the Moodle program files? Can your web server read and write your Moodle data directory?
* Check your database permissions. Have you set up your database user with the correct rights and permissions for your configuration (especially if the web server and database server are different machines)?
* Create your [[Configuration file]] (config.php) by hand. Copy config-dist.php (in the root of the Moodle program directory) to config.php, edit it and set your database/site options there. Installation will continue from the right place.
* Once you have a config.php (see previous tip) you can edit it to turn on debugging (in section 8). This may give you extra information to help track down a problem. If you have access, check your web server error log(s).
* Re-check your php.ini / .htaccess settings. Are they appropriate (e.g. memory_limit), did you edit the correct php.ini / .htaccess file and (if required) did you re-start the web server after making changes?
* Did you include any non-core (optional) plugins, themes or other code before starting the installation script? If so, remove it and try again (it may be broken or incompatible).
* Explain your problem in the [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]. '''PLEASE''' list your software versions; explain what you did, what happened and what error messages you saw (if any); explain what you tried. There is no such thing as 'nothing', even a blank page is something!

== Platform specific instructions ==

'''Note:''' Much of this information is provided by the community. It may not have been checked and may be out of date. Please read in conjunction with the above installation instructions.

* [[Windows installation]]
** [[Installing Moodle on SmarterASP.NET]]
* [[Unix or Linux Installation]]
* [[Mac Installation]]
* [[Amazon EC2 Cloud Services Installation]]

== See also ==
* [http://www.slideshare.net/gb2048/my-own-moodle Slideshare presentation by Gareth Barnard on installing a local installation of Moodle] and accompanying [https://drive.google.com/folderview?id=0B17B0rYH2zERU21sQnVweUZCUFk&usp=sharing help guides]
* [http://moodle.org/mod/forum/discuss.php?d=182086 New Video Tutorial- How to Install Moodle on Shared Hosting via cPanel (Not Fantastico)]
* [http://moodle.org/mod/forum/discuss.php?d=199542 Video Tutorial - Install Moodle on a Virtual Box from scratch]

[[es:Instalaci%C3%B3n_de_moodle]]
[[de:Installation von Moodle]]
[[fr:Installation de Moodle]]
[[ja:Moodleのインストール]]

Installing Moodle

2015-11-05T08:33:15Z

Mrverrall: /* Hardware */ 3.0rc1 is 193MB, round up to 200MB requirement.

{{Template:Installing Moodle}}
''This page explains how to install Moodle. If you are an expert and/or in a hurry try [[Installation Quickstart]].''

If you just want to try Moodle on a standalone machine there are 'one-click' installers for Windows (see [[Complete install packages for Windows]]) and for OSX (see [[Complete Install Packages for Mac OS X]]) or [[ install on OS X]]. These are unsuitable for production servers.

== Requirements ==

Moodle is primarily developed in Linux using [[Apache]], [[PostgreSQL]]/[[MySQL]]/[[MariaDB]] and [[PHP]] (also sometimes known as the LAMP platform). If in doubt, this is the safest combination (if for no other reason than being the most common). There are other options - see the Software section that follows:

If you are installing Moodle in a Windows server, note that from php5.5 onwards, you will also need to have the Visual C++ Redistributable for Visual Studio 2012 installed from:
http://www.microsoft.com/en-us/download/details.aspx?id=30679 Visual C++] ( x86 or x64)

The basic requirements for Moodle are as follows:

=== Hardware ===
* Disk space: 200MB for the Moodle code, plus as much as you need to store content. 5GB is probably a realistic minimum.
* Processor: 1GHz (min), 2GHz dual core recommended. These settings may vary according to the resources used.
* Backups: at least the same again (at a remote location preferably) as above to keep backups of your site.
* Memory: 256MB (min), 1GB or more is strongly recommended.

All the above requirements will vary depending on specific hardware and software combinations as well as the type of use and load; busy sites may well require additional resources. Further guidance can be found under [[Performance_recommendations|performance recommendations]].

=== Software ===

See the [{{Release notes}} release notes] in the dev docs for software requirements.

== Set up your server ==

...or desktop computer, if you are just evaluating Moodle. There are lots of possibilities for installing the basic server software depending on your particular choices. Some links and pointers are at [[Installing AMP]], [[Internet_Information_Services|IIS]], [[Nginx]]

If you are using a hosted server all this should be done for you. However, (especially on shared hosting) make sure you understand or find out how to change PHP settings (e.g. file upload maximums). This can vary a huge amount from host to host. You also need to verify that your webhost supports the required php version for the Moodle installation you are installing.

== Download and copy files into place ==

'''IMPORTANT: While there are now a number of places you can get the Moodle code, you are strongly advised to obtain Moodle from moodle.org. If you run into problems it will be a great deal easier to support you.'''

You have two options:
* Download your required version from http://moodle.org/downloads and unzip/unpack...
* '''OR''' Pull the code from the Git repository (recommended for developers and also makes upgrading very simple):
<pre>
$ git clone --depth=1 -b MOODLE_30_STABLE git://git.moodle.org/moodle.git
</pre>
--depth=1 for shallow cloning (only) latest revision

--single-branch option to limit cloning to a single branch, this fetches the Moodle 3.0 Stable branch (latest weekly build). For a fuller discussion see [[Git for Administrators]].

Either of the above should result in a directory called '''moodle''', containing a number of files and folders.

You can either place the whole folder in your web server documents directory, in which case the site will be located at '''<nowiki>http://yourwebserver.com/moodle</nowiki>''', or you can copy all the contents straight into the main web server documents directory, in which case the site will be simply '''<nowiki>http://yourwebserver.com</nowiki>'''. See the documentation for your system and/or web server if you are unsure.

:''Tip:'' If you are downloading Moodle to your local computer and then uploading it to your hosted web site, if possible upload the compressed file and decompress at the remote end (check your 'file manager'). Failing that, watch FTP progress carefully for errors or missed files.

* '''Secure the Moodle files:''' It is vital that the files are not writeable by the web server user. For example, on Unix/Linux (as root):
<pre>
# chown -R root /path/to/moodle
# chmod -R 0755 /path/to/moodle
# find /path/to/moodle -type f -exec chmod 0644 {} \;
</pre>
(files are owned by the administrator/superuser and are only writeable by them - readable by everyone else)

The third command finds all the regular files and executes the chmod command 0644 on them.

If you want to use the built-in plugin installer you need to make the directory writable by web server user. It is strongly recommended to use ACL when your server supports it, for example if your Apache server uses account www-data:

<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodle
</pre>

The effect of the previous command is to allow the Apache user account (www-data in this case) to access and change files within the moodle site. Many people would consider this a brave move for a new site admin to implement. In a new moodle you can safely leave this out. A default Ubuntu install does not have the +a option for the chmod command anyway. The +a attribute is an ACL (Access Control List) facility which allows you to set per user access for individual files. For example, OSX has this by default.

== Create an empty database ==

Next create a new, empty database for your installation. You need to find and make a note of following information for use during the final installation stage:
* '''dbhost''' - the database server hostname. Probably ''localhost'' if the database and web server are the same machine, otherwise the name of the database server
* '''dbname''' - the database name. Whatever you called it, e.g. ''moodle''
* '''dbuser''' - the username for the database. Whatever you assigned, e.g. ''moodleuser'' - do not use the root/superuser account. Create a proper account with the minimum permissions needed.
* '''dbpass''' - the password for the above user

If your site is hosted you should find a web-based administration page for databases as part of the control panel (or ask your administrator). For everyone else or for detailed instructions, see the page for your chosen database server:
* [[PostgreSQL]]
* [[MariaDB]]
* [[MySQL]]
* [[MSSQL]]
* [[Oracle]] (known issues, not fully supported - see MDL-41310)

== Create the (''moodledata'') data directory ==

Moodle requires a directory to store all of its files (all your site's uploaded files, temporary data, cache, session data etc.). The web server needs to be able to write to this directory. On larger systems consider how much free space you are going to use when allocating this directory.

Due to the way Moodle caches data you may have performance issues if you use relatively slow storage (e.g. NFS) for this directory. Read the [[Performance_recommendations]] carefully and consider using (e.g.) memcached for [[Caching]].

'''IMPORTANT:''' This directory must '''NOT''' be accessible directly via the web. This would be a serious security hole. Do not try to place it inside your web root or inside your Moodle program files directory. Moodle will not install. It can go anywhere else convenient.

Here is an example (Unix/Linux) of creating the directory and setting the permissions for '''anyone''' on the server to write here. This is only appropriate for Moodle servers that are not shared. Discuss this with your server administrator for better permissions that just allow the web server user to access these files.

<pre>
# mkdir /path/to/moodledata
# chmod 0777 /path/to/moodledata
</pre>

If your server supports ACL it is recommended to set following permissions, for example if your Apache server uses account www-data:
<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>
If you are planning to execute PHP scripts from the command line you should set the same permissions for the current user:
<pre>
$ sudo chmod -R +a "`whoami` allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>

==== Securing moodledata in a web directory ====

If you are using a hosted site and you have no option but to place 'moodledata' in a web accessible directory. You may be able to secure it by creating an .htaccess file in the 'moodledata' directory. This does not work on all systems - see your host/administrator. Create a file called .htaccess containing only the following lines:
<pre>
order deny,allow
deny from all
</pre>

== Start Moodle install ==
It's now time to run the installer to create the database tables and configure your new site. The recommended method is to use the command line installer. If you cannot do this for any reason (e.g. on a Windows server) the web based installer is still available.

=== Command line installer ===

It's best to run the command line as your system's web user. You need to know what that is - see your system's documentation (e.g. Ubuntu/Debian is 'www-data', Centos is 'apache')

* Example of using the command-line (as root - substitute 'www-data' for your web user):
<pre>
# chown www-data /path/to/moodle
# cd /path/to/moodle/admin/cli
# sudo -u www-data /usr/bin/php install.php
# chown -R root /path/to/moodle
</pre>
The chowns allow the script to write a new config.php file. More information about the options can be found using
<pre>
# php install.php --help
</pre>

You will be asked for other settings that have not been discussed on this page - if unsure just accept the defaults. For a full discussion see [[Administration via command line]]

=== Web based installer ===
To run the web installer script, just go to your Moodle's main URL using a web browser.

The installation process will take you through a number of pages. You should be asked to confirm the copyright, see the database tables being created, supply administrator account details and supply the site details. The database creation can take some time - please be patient. You should eventually end up at the Moodle front page with an invitation to create a new course.

It is very likely that you will be asked to download the new config.php file and upload it to your Moodle installation - just follow the on-screen instructions.

==Final configuration==

=== Settings within Moodle ===
There are a number of options within the Moodle Site Administration screens (accessible from the 'Site administration' tab in the 'Administration' block. Here are a few of the more important ones that you will probably want to check:
* ''Administration > Site administration > Plugins > Message Outputs > Email'': Set your smtp server and authentication if required (so your Moodle site can send emails). The support contact for your site is also set on this page.
* ''Administration > Site administration > Server > System paths'': Set the paths to du, dot and aspell binaries.
* ''Administration > Site administration > Server > HTTP'': If you are behind a firewall you may need to set your proxy credentials in the 'Web proxy' section.
* ''Administration > Site administration > Location > Update timezones'': Run this to make sure your timezone information is up to date. (more info [[Location]])
** [http://php.net/manual/en/timezones.php Set server's local timezone] inside <tt>php.ini</tt> (should probably be inside <tt>/etc/php.ini</tt> or <tt>/etc/php.d/date.ini</tt>, depending on the underline OS):
**: <code ini>[Date]
; Defines the default timezone used by the date functions
date.timezone = "YOUR LOCAL TIMEZONE"</code>

=== Remaining tasks ===

* '''Configure Cron''': Moodle's background tasks (e.g. sending out forum emails and performing course backups) are performed by a script which you can set to execute at specific times of the day. This is known as a cron script. Please refer to the [[Cron|Cron instructions]].
* '''Set up backups''': See [[Site backup]] and [[Automated course backup]].
* '''Check mail works''': [[Add a new user|Create a test user]] with a valid email address and [[message|send them a message]]. Do they receive an email copy of the message? If not, check the settings in ''Settings > Site administration > Plugins > Message outputs > Email''. Don't be tempted to skip this step (clue: email is used to recover lost passwords, including the administrator password when you forget it!)
* '''Secure your Moodle site''': Read the [[Security recommendations]].
*'''Increasing the maximum upload size''' See [[Installation FAQ]] Maximum upload file size - how to change it?

=== Installation is complete :) ===

* Create a new course: You can now [[Adding a new course|create a new course]] and have a play ;-)

=== If something goes wrong... ===

Here are some things you should try...

* Check the [[Installation FAQ]]
* Check your file permissions carefully. Can your web server read (but not write) the Moodle program files? Can your web server read and write your Moodle data directory?
* Check your database permissions. Have you set up your database user with the correct rights and permissions for your configuration (especially if the web server and database server are different machines)?
* Create your [[Configuration file]] (config.php) by hand. Copy config-dist.php (in the root of the Moodle program directory) to config.php, edit it and set your database/site options there. Installation will continue from the right place.
* Once you have a config.php (see previous tip) you can edit it to turn on debugging (in section 8). This may give you extra information to help track down a problem. If you have access, check your web server error log(s).
* Re-check your php.ini / .htaccess settings. Are they appropriate (e.g. memory_limit), did you edit the correct php.ini / .htaccess file and (if required) did you re-start the web server after making changes?
* Did you include any non-core (optional) plugins, themes or other code before starting the installation script? If so, remove it and try again (it may be broken or incompatible).
* Explain your problem in the [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]. '''PLEASE''' list your software versions; explain what you did, what happened and what error messages you saw (if any); explain what you tried. There is no such thing as 'nothing', even a blank page is something!

== Platform specific instructions ==

'''Note:''' Much of this information is provided by the community. It may not have been checked and may be out of date. Please read in conjunction with the above installation instructions.

* [[Windows installation]]
** [[Installing Moodle on SmarterASP.NET]]
* [[Unix or Linux Installation]]
* [[Mac Installation]]
* [[Amazon EC2 Cloud Services Installation]]

== See also ==
* [http://www.slideshare.net/gb2048/my-own-moodle Slideshare presentation by Gareth Barnard on installing a local installation of Moodle] and accompanying [https://drive.google.com/folderview?id=0B17B0rYH2zERU21sQnVweUZCUFk&usp=sharing help guides]
* [http://moodle.org/mod/forum/discuss.php?d=182086 New Video Tutorial- How to Install Moodle on Shared Hosting via cPanel (Not Fantastico)]
* [http://moodle.org/mod/forum/discuss.php?d=199542 Video Tutorial - Install Moodle on a Virtual Box from scratch]

[[es:Instalaci%C3%B3n_de_moodle]]
[[de:Installation von Moodle]]
[[fr:Installation de Moodle]]
[[ja:Moodleのインストール]]

Installing Moodle

2015-11-03T12:11:08Z

Mrverrall: /* Hardware */

{{Template:Installing Moodle}}
''This page explains how to install Moodle. If you are an expert and/or in a hurry try [[Installation Quickstart]].''

If you just want to try Moodle on a standalone machine there are 'one-click' installers for Windows (see [[Complete install packages for Windows]]) and for OSX (see [[Complete Install Packages for Mac OS X]]) or [[ install on OS X]]. These are unsuitable for production servers.

== Requirements ==

Moodle is primarily developed in Linux using [[Apache]], [[PostgreSQL]]/[[MySQL]]/[[MariaDB]] and [[PHP]] (also sometimes known as the LAMP platform). If in doubt, this is the safest combination (if for no other reason than being the most common). There are other options - see the Software section that follows:

If you are installing Moodle in a Windows server, note that from php5.5 onwards, you will also need to have the Visual C++ Redistributable for Visual Studio 2012 installed from:
http://www.microsoft.com/en-us/download/details.aspx?id=30679 Visual C++] ( x86 or x64)

The basic requirements for Moodle are as follows:

=== Hardware ===
* Disk space: 160MB free (min) plus as much as you need to store your materials. 5GB is probably a realistic minimum.
* Processor: 1GHz (min), 2GHz dual core recommended. These settings may vary according to the resources used.
* Backups: at least the same again (at a remote location preferably) as above to keep backups of your site.
* Memory: 256MB (min), 1GB or more is strongly recommended.

All the above requirements will vary depending on specific hardware and software combinations as well as the type of use and load; busy sites may well require additional resources. Further guidance can be found under [[Performance_recommendations|performance recommendations]].

=== Software ===

See the [{{Release notes}} release notes] in the dev docs for software requirements.

== Set up your server ==

...or desktop computer, if you are just evaluating Moodle. There are lots of possibilities for installing the basic server software depending on your particular choices. Some links and pointers are at [[Installing AMP]], [[Internet_Information_Services|IIS]], [[Nginx]]

If you are using a hosted server all this should be done for you. However, (especially on shared hosting) make sure you understand or find out how to change PHP settings (e.g. file upload maximums). This can vary a huge amount from host to host. You also need to verify that your webhost supports the required php version for the Moodle installation you are installing.

== Download and copy files into place ==

'''IMPORTANT: While there are now a number of places you can get the Moodle code, you are strongly advised to obtain Moodle from moodle.org. If you run into problems it will be a great deal easier to support you.'''

You have two options:
* Download your required version from http://moodle.org/downloads and unzip/unpack...
* '''OR''' Pull the code from the Git repository (recommended for developers and also makes upgrading very simple):
<pre>
$ git clone --depth=1 -b MOODLE_30_STABLE git://git.moodle.org/moodle.git
</pre>
--depth=1 for shallow cloning (only) latest revision

--single-branch option to limit cloning to a single branch, this fetches the Moodle 3.0 Stable branch (latest weekly build). For a fuller discussion see [[Git for Administrators]].

Either of the above should result in a directory called '''moodle''', containing a number of files and folders.

You can either place the whole folder in your web server documents directory, in which case the site will be located at '''<nowiki>http://yourwebserver.com/moodle</nowiki>''', or you can copy all the contents straight into the main web server documents directory, in which case the site will be simply '''<nowiki>http://yourwebserver.com</nowiki>'''. See the documentation for your system and/or web server if you are unsure.

:''Tip:'' If you are downloading Moodle to your local computer and then uploading it to your hosted web site, if possible upload the compressed file and decompress at the remote end (check your 'file manager'). Failing that, watch FTP progress carefully for errors or missed files.

* '''Secure the Moodle files:''' It is vital that the files are not writeable by the web server user. For example, on Unix/Linux (as root):
<pre>
# chown -R root /path/to/moodle
# chmod -R 0755 /path/to/moodle
# find /path/to/moodle -type f -exec chmod 0644 {} \;
</pre>
(files are owned by the administrator/superuser and are only writeable by them - readable by everyone else)

The third command finds all the regular files and executes the chmod command 0644 on them.

If you want to use the built-in plugin installer you need to make the directory writable by web server user. It is strongly recommended to use ACL when your server supports it, for example if your Apache server uses account www-data:

<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodle
</pre>

The effect of the previous command is to allow the Apache user account (www-data in this case) to access and change files within the moodle site. Many people would consider this a brave move for a new site admin to implement. In a new moodle you can safely leave this out. A default Ubuntu install does not have the +a option for the chmod command anyway. The +a attribute is an ACL (Access Control List) facility which allows you to set per user access for individual files. For example, OSX has this by default.

== Create an empty database ==

Next create a new, empty database for your installation. You need to find and make a note of following information for use during the final installation stage:
* '''dbhost''' - the database server hostname. Probably ''localhost'' if the database and web server are the same machine, otherwise the name of the database server
* '''dbname''' - the database name. Whatever you called it, e.g. ''moodle''
* '''dbuser''' - the username for the database. Whatever you assigned, e.g. ''moodleuser'' - do not use the root/superuser account. Create a proper account with the minimum permissions needed.
* '''dbpass''' - the password for the above user

If your site is hosted you should find a web-based administration page for databases as part of the control panel (or ask your administrator). For everyone else or for detailed instructions, see the page for your chosen database server:
* [[PostgreSQL]]
* [[MariaDB]]
* [[MySQL]]
* [[MSSQL]]
* [[Oracle]] (known issues, not fully supported - see MDL-41310)

== Create the (''moodledata'') data directory ==

Moodle requires a directory to store all of its files (all your site's uploaded files, temporary data, cache, session data etc.). The web server needs to be able to write to this directory. On larger systems consider how much free space you are going to use when allocating this directory.

Due to the way Moodle caches data you may have performance issues if you use relatively slow storage (e.g. NFS) for this directory. Read the [[Performance_recommendations]] carefully and consider using (e.g.) memcached for [[Caching]].

'''IMPORTANT:''' This directory must '''NOT''' be accessible directly via the web. This would be a serious security hole. Do not try to place it inside your web root or inside your Moodle program files directory. Moodle will not install. It can go anywhere else convenient.

Here is an example (Unix/Linux) of creating the directory and setting the permissions for '''anyone''' on the server to write here. This is only appropriate for Moodle servers that are not shared. Discuss this with your server administrator for better permissions that just allow the web server user to access these files.

<pre>
# mkdir /path/to/moodledata
# chmod 0777 /path/to/moodledata
</pre>

If your server supports ACL it is recommended to set following permissions, for example if your Apache server uses account www-data:
<pre>
# chmod -R +a "www-data allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>
If you are planning to execute PHP scripts from the command line you should set the same permissions for the current user:
<pre>
$ sudo chmod -R +a "`whoami` allow read,delete,write,append,file_inherit,directory_inherit" /path/to/moodledata
</pre>

==== Securing moodledata in a web directory ====

If you are using a hosted site and you have no option but to place 'moodledata' in a web accessible directory. You may be able to secure it by creating an .htaccess file in the 'moodledata' directory. This does not work on all systems - see your host/administrator. Create a file called .htaccess containing only the following lines:
<pre>
order deny,allow
deny from all
</pre>

== Start Moodle install ==
It's now time to run the installer to create the database tables and configure your new site. The recommended method is to use the command line installer. If you cannot do this for any reason (e.g. on a Windows server) the web based installer is still available.

=== Command line installer ===

It's best to run the command line as your system's web user. You need to know what that is - see your system's documentation (e.g. Ubuntu/Debian is 'www-data', Centos is 'apache')

* Example of using the command-line (as root - substitute 'www-data' for your web user):
<pre>
# chown www-data /path/to/moodle
# cd /path/to/moodle/admin/cli
# sudo -u www-data /usr/bin/php install.php
# chown -R root /path/to/moodle
</pre>
The chowns allow the script to write a new config.php file. More information about the options can be found using
<pre>
# php install.php --help
</pre>

You will be asked for other settings that have not been discussed on this page - if unsure just accept the defaults. For a full discussion see [[Administration via command line]]

=== Web based installer ===
To run the web installer script, just go to your Moodle's main URL using a web browser.

The installation process will take you through a number of pages. You should be asked to confirm the copyright, see the database tables being created, supply administrator account details and supply the site details. The database creation can take some time - please be patient. You should eventually end up at the Moodle front page with an invitation to create a new course.

It is very likely that you will be asked to download the new config.php file and upload it to your Moodle installation - just follow the on-screen instructions.

==Final configuration==

=== Settings within Moodle ===
There are a number of options within the Moodle Site Administration screens (accessible from the 'Site administration' tab in the 'Administration' block. Here are a few of the more important ones that you will probably want to check:
* ''Administration > Site administration > Plugins > Message Outputs > Email'': Set your smtp server and authentication if required (so your Moodle site can send emails). The support contact for your site is also set on this page.
* ''Administration > Site administration > Server > System paths'': Set the paths to du, dot and aspell binaries.
* ''Administration > Site administration > Server > HTTP'': If you are behind a firewall you may need to set your proxy credentials in the 'Web proxy' section.
* ''Administration > Site administration > Location > Update timezones'': Run this to make sure your timezone information is up to date. (more info [[Location]])
** [http://php.net/manual/en/timezones.php Set server's local timezone] inside <tt>php.ini</tt> (should probably be inside <tt>/etc/php.ini</tt> or <tt>/etc/php.d/date.ini</tt>, depending on the underline OS):
**: <code ini>[Date]
; Defines the default timezone used by the date functions
date.timezone = "YOUR LOCAL TIMEZONE"</code>

=== Remaining tasks ===

* '''Configure Cron''': Moodle's background tasks (e.g. sending out forum emails and performing course backups) are performed by a script which you can set to execute at specific times of the day. This is known as a cron script. Please refer to the [[Cron|Cron instructions]].
* '''Set up backups''': See [[Site backup]] and [[Automated course backup]].
* '''Check mail works''': [[Add a new user|Create a test user]] with a valid email address and [[message|send them a message]]. Do they receive an email copy of the message? If not, check the settings in ''Settings > Site administration > Plugins > Message outputs > Email''. Don't be tempted to skip this step (clue: email is used to recover lost passwords, including the administrator password when you forget it!)
* '''Secure your Moodle site''': Read the [[Security recommendations]].
*'''Increasing the maximum upload size''' See [[Installation FAQ]] Maximum upload file size - how to change it?

=== Installation is complete :) ===

* Create a new course: You can now [[Adding a new course|create a new course]] and have a play ;-)

=== If something goes wrong... ===

Here are some things you should try...

* Check the [[Installation FAQ]]
* Check your file permissions carefully. Can your web server read (but not write) the Moodle program files? Can your web server read and write your Moodle data directory?
* Check your database permissions. Have you set up your database user with the correct rights and permissions for your configuration (especially if the web server and database server are different machines)?
* Create your [[Configuration file]] (config.php) by hand. Copy config-dist.php (in the root of the Moodle program directory) to config.php, edit it and set your database/site options there. Installation will continue from the right place.
* Once you have a config.php (see previous tip) you can edit it to turn on debugging (in section 8). This may give you extra information to help track down a problem. If you have access, check your web server error log(s).
* Re-check your php.ini / .htaccess settings. Are they appropriate (e.g. memory_limit), did you edit the correct php.ini / .htaccess file and (if required) did you re-start the web server after making changes?
* Did you include any non-core (optional) plugins, themes or other code before starting the installation script? If so, remove it and try again (it may be broken or incompatible).
* Explain your problem in the [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]. '''PLEASE''' list your software versions; explain what you did, what happened and what error messages you saw (if any); explain what you tried. There is no such thing as 'nothing', even a blank page is something!

== Platform specific instructions ==

'''Note:''' Much of this information is provided by the community. It may not have been checked and may be out of date. Please read in conjunction with the above installation instructions.

* [[Windows installation]]
** [[Installing Moodle on SmarterASP.NET]]
* [[Unix or Linux Installation]]
* [[Mac Installation]]
* [[Amazon EC2 Cloud Services Installation]]

== See also ==
* [http://www.slideshare.net/gb2048/my-own-moodle Slideshare presentation by Gareth Barnard on installing a local installation of Moodle] and accompanying [https://drive.google.com/folderview?id=0B17B0rYH2zERU21sQnVweUZCUFk&usp=sharing help guides]
* [http://moodle.org/mod/forum/discuss.php?d=182086 New Video Tutorial- How to Install Moodle on Shared Hosting via cPanel (Not Fantastico)]
* [http://moodle.org/mod/forum/discuss.php?d=199542 Video Tutorial - Install Moodle on a Virtual Box from scratch]

[[es:Instalaci%C3%B3n_de_moodle]]
[[de:Installation von Moodle]]
[[fr:Installation de Moodle]]
[[ja:Moodleのインストール]]

MUC FAQ

2015-10-06T13:59:51Z

Mrverrall: /* How can I tell what Cache store I am really using */

{{Performance}}

The Moodle Unified Cache (MUC) on initial inspection can appear to be a complex
off-putting beast, and this can lead to it either being ignored or, as is
often the case, poorly configured.

Here is what you need to know (so you can ignore [https://docs.moodle.org/310/en/Caching the rest]).

==What is the MUC?==

The MUC is a cache, a cache is a store of data which is easier/faster to
retrieve than if it came from it's source. It saves (computing) effort and makes Moodle
faster.

==Should I be using the MUC?==

Yes, and if you are using Moodle 2.4 or above you are already using the MUC.

If your site is already running fine then consider '''not changing anything''' as "[https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize premature optimization is the root of all evil]".

By default MUC uses the file system to store it's cached objects, this already speeds thing up greatly than if there was no MUC at all. By further configuring the MUC we are just trying to make it faster.

==What is wrong with the default file-system MUC?==

Not much at all, but the MUCs performance is dependant on the read/write speed of it's storage medium.

Typically disks are slow but safe (persistent) storage. MUC data does not need to kept safe
as it can always be regenerated so it can afford to be kept somewhere fast yet volatile, like RAM.

==How can I make MUC faster?==

Using a RAM based cache is the best way to make the MUC fast and there a few tools we can use for this, such as, tmpfs, Memcached, APC,
Redis and overtime probably more... A good place to start if you are unsure of any specific requirements is Memcached as it is common, well tested, fast and easy to deploy.

==How do I deploy Memcached==

This is by no means exhaustive, and will vary depending on your OS etc. But for simplicities sake...

* Install Memcached in a way compatible with your operating system e.g. in Debian/Ubuntu
apt-get install memcached
* Confiure Memcached, or at least become aware of it's default setup, e.g.
** 64MB of RAM allocation
** Runs on port 11211
* Make sure your PHP has the required support, e.g. in Debian/Ubuntu
apt-get install php5-memcached
* In Moodle go to
**'Site administration > Plugins > Caching > Configuration'
**Under '''Installed cache stores''' you should see Memcached and an '''Add instance''' action. Click '''Add Instance'''.
**Give the store a name, i like 'Memcached_MUC'
**In '''server''', assuming the basic config above, type 'localhost'. '''Save Changes'''.
**Scroll to the bottom of the '''Cache administration''' page you were returned to.
**Under '''Stores used when no mapping is present''' click '''Edit Mappings'''.
**In the '''Application''' drop down select your caches name. '''Save Changes'''.
* Profit

More details can be found in the main [https://docs.moodle.org/310/en/Caching#Memcached Caching documentaion].

==How much memory should I allocate to MUC?==
Less then you probably think! The default on most Memcached deployments is
64MB and this is probably '''more''' than enough for a pretty standard Moodle
install. As a real world example, checking a live site with ~6000 individual user
logins, over the last 24 hours was using 11MB of Memcached MUC (Moodle 2.8 with 26 additional
plugins).

Most importantly if you decide to implement an in memory cache like Memcached then monitor and understand its use in '''your''' deployment as this can vary wildly.

==I'm already using Memcached for sessions, can I just reuse that?==
Nope, afraid not. If the MUC purges so will sessions, all your users will be
logged out. That does not stop you using two memcached instances, one for
sessions and one MUC. An example of how to do this can be found [https://moopi.mrverrall.co.uk/course/view.php?id=4#section-5 here].

==How can I tell what Cache store I am really using==
[[File:perf.png|thumb|300px]]
If you temporarily switch on performance debugging at '''Site administration Development > Debugging > Performance info''' some useful information is displayed the the footer of all your pages. This includes information about the MUC cache objects set and retrieved as well as the cachestore they came from.

==I have a cluster of servers, <further question here>?==

You are probably beyond the target audience of this FAQ in terms of your system
administration foo.

==What is that little grey triangle?==
[[File:muc-triangle.png|thumb|300px]]
This happens when the default Application Cache does not support a requirement
of one or more of the '''cache definitions'''. Do not panic, it is not important.

For example, of the default application caches only '''Event Invalidation''' is not supported
by Memcached.

Event Invalidation requires '''Data Guarantee''' which ensures data exists in the
cache once it is put there. It is '''never''' cleaned up to free space or because
it has not been recently used. Because (as discussed above/below?) Memcached
evicts objects form it's cache it cannot be used Event Invalidation.

The Event Invalidation cache is used to ENSURE events are handled correctly,
i.e. the objects exist when they are created and don't exist '''only''' when they are purged,
this may not occur if the cache object vanishes unexpectedly as may be the case with Memcached.

So Event Invalidation will just carry on using the file-system cache (or
whatever else you tell it too).

==Where can I find more documentation on setting up the MUC?==
There is some great documemntaion on this site, the [https://docs.moodle.org/310/en/Caching Caching] page is probably your best place to start.

If you are further interested in the nuts and bolts of the caching system, e.g. cache features (ttl, data guarantee, etc) the [https://github.com/moodle/moodle/blob/master/cache/README.md developers api] is a good place to look.

MUC FAQ

2015-10-06T13:59:11Z

Mrverrall:

{{Performance}}

The Moodle Unified Cache (MUC) on initial inspection can appear to be a complex
off-putting beast, and this can lead to it either being ignored or, as is
often the case, poorly configured.

Here is what you need to know (so you can ignore [https://docs.moodle.org/310/en/Caching the rest]).

==What is the MUC?==

The MUC is a cache, a cache is a store of data which is easier/faster to
retrieve than if it came from it's source. It saves (computing) effort and makes Moodle
faster.

==Should I be using the MUC?==

Yes, and if you are using Moodle 2.4 or above you are already using the MUC.

If your site is already running fine then consider '''not changing anything''' as "[https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize premature optimization is the root of all evil]".

By default MUC uses the file system to store it's cached objects, this already speeds thing up greatly than if there was no MUC at all. By further configuring the MUC we are just trying to make it faster.

==What is wrong with the default file-system MUC?==

Not much at all, but the MUCs performance is dependant on the read/write speed of it's storage medium.

Typically disks are slow but safe (persistent) storage. MUC data does not need to kept safe
as it can always be regenerated so it can afford to be kept somewhere fast yet volatile, like RAM.

==How can I make MUC faster?==

Using a RAM based cache is the best way to make the MUC fast and there a few tools we can use for this, such as, tmpfs, Memcached, APC,
Redis and overtime probably more... A good place to start if you are unsure of any specific requirements is Memcached as it is common, well tested, fast and easy to deploy.

==How do I deploy Memcached==

This is by no means exhaustive, and will vary depending on your OS etc. But for simplicities sake...

* Install Memcached in a way compatible with your operating system e.g. in Debian/Ubuntu
apt-get install memcached
* Confiure Memcached, or at least become aware of it's default setup, e.g.
** 64MB of RAM allocation
** Runs on port 11211
* Make sure your PHP has the required support, e.g. in Debian/Ubuntu
apt-get install php5-memcached
* In Moodle go to
**'Site administration > Plugins > Caching > Configuration'
**Under '''Installed cache stores''' you should see Memcached and an '''Add instance''' action. Click '''Add Instance'''.
**Give the store a name, i like 'Memcached_MUC'
**In '''server''', assuming the basic config above, type 'localhost'. '''Save Changes'''.
**Scroll to the bottom of the '''Cache administration''' page you were returned to.
**Under '''Stores used when no mapping is present''' click '''Edit Mappings'''.
**In the '''Application''' drop down select your caches name. '''Save Changes'''.
* Profit

More details can be found in the main [https://docs.moodle.org/310/en/Caching#Memcached Caching documentaion].

==How much memory should I allocate to MUC?==
Less then you probably think! The default on most Memcached deployments is
64MB and this is probably '''more''' than enough for a pretty standard Moodle
install. As a real world example, checking a live site with ~6000 individual user
logins, over the last 24 hours was using 11MB of Memcached MUC (Moodle 2.8 with 26 additional
plugins).

Most importantly if you decide to implement an in memory cache like Memcached then monitor and understand its use in '''your''' deployment as this can vary wildly.

==I'm already using Memcached for sessions, can I just reuse that?==
Nope, afraid not. If the MUC purges so will sessions, all your users will be
logged out. That does not stop you using two memcached instances, one for
sessions and one MUC. An example of how to do this can be found [https://moopi.mrverrall.co.uk/course/view.php?id=4#section-5 here].

==How can I tell what Cache store I am really using==
[[File:perf.png|thumb|300px]]
If you temporarily switch on performance debugging at '''Site administration Development > Debugging > Performance info''' some useful information is displayed teh the footer of all your moodle pages. This includes information about the MUC cache objects set and retrieved as well as the cachestore they came from.

Sometimes, even if you think you have set it up perfectly Moodle will silently fail over to using the default cache stores if it encounters a problem

==I have a cluster of servers, <further question here>?==

You are probably beyond the target audience of this FAQ in terms of your system
administration foo.

==What is that little grey triangle?==
[[File:muc-triangle.png|thumb|300px]]
This happens when the default Application Cache does not support a requirement
of one or more of the '''cache definitions'''. Do not panic, it is not important.

For example, of the default application caches only '''Event Invalidation''' is not supported
by Memcached.

Event Invalidation requires '''Data Guarantee''' which ensures data exists in the
cache once it is put there. It is '''never''' cleaned up to free space or because
it has not been recently used. Because (as discussed above/below?) Memcached
evicts objects form it's cache it cannot be used Event Invalidation.

The Event Invalidation cache is used to ENSURE events are handled correctly,
i.e. the objects exist when they are created and don't exist '''only''' when they are purged,
this may not occur if the cache object vanishes unexpectedly as may be the case with Memcached.

So Event Invalidation will just carry on using the file-system cache (or
whatever else you tell it too).

==Where can I find more documentation on setting up the MUC?==
There is some great documemntaion on this site, the [https://docs.moodle.org/310/en/Caching Caching] page is probably your best place to start.

If you are further interested in the nuts and bolts of the caching system, e.g. cache features (ttl, data guarantee, etc) the [https://github.com/moodle/moodle/blob/master/cache/README.md developers api] is a good place to look.

File:perf.png

2015-10-06T13:57:59Z

Mrverrall: Example of the on-screen performance information displayed in the footer when 'Site administration > Development > Debugging > Performance' info is enabled

Example of the on-screen performance information displayed in the footer when 'Site administration > Development > Debugging > Performance' info is enabled

MUC FAQ

2015-10-06T13:39:01Z

Mrverrall: /* Where can I find more documentation on setting up the MUC? */

{{Performance}}

The Moodle Unified Cache (MUC) on initial inspection can appear to be a complex
off-putting beast, and this can lead to it either being ignored or, as is
often the case, poorly configured.

Here is what you need to know (so you can ignore [https://docs.moodle.org/310/en/Caching the rest]).

==What is the MUC?==

The MUC is a cache, a cache is a store of data which is easier/faster to
retrieve than if it came from it's source. It saves (computing) effort and makes Moodle
faster.

==Should I be using the MUC?==

Yes, and if you are using Moodle 2.4 or above you are already using the MUC.

If your site is already running fine then consider '''not changing anything''' as "[https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize premature optimization is the root of all evil]".

By default MUC uses the file system to store it's cached objects, this already speeds thing up greatly than if there was no MUC at all. By further configuring the MUC we are just trying to make it faster.

==What is wrong with the default file-system MUC?==

Not much at all, but the MUCs performance is dependant on the read/write speed of it's storage medium.

Typically disks are slow but safe (persistent) storage. MUC data does not need to kept safe
as it can always be regenerated so it can afford to be kept somewhere fast yet volatile, like RAM.

==How can I make MUC faster?==

Using a RAM based cache is the best way to make the MUC fast and there a few tools we can use for this, such as, tmpfs, Memcached, APC,
Redis and overtime probably more... A good place to start if you are unsure of any specific requirements is Memcached as it is common, well tested, fast and easy to deploy.

==How do I deploy Memcached==

This is by no means exhaustive, and will vary depending on your OS etc. But for simplicities sake...

* Install Memcached in a way compatible with your operating system e.g. in Debian/Ubuntu
apt-get install memcached
* Confiure Memcached, or at least become aware of it's default setup, e.g.
** 64MB of RAM allocation
** Runs on port 11211
* Make sure your PHP has the required support, e.g. in Debian/Ubuntu
apt-get install php5-memcached
* In Moodle go to
**'Site administration > Plugins > Caching > Configuration'
**Under '''Installed cache stores''' you should see Memcached and an '''Add instance''' action. Click '''Add Instance'''.
**Give the store a name, i like 'Memcached_MUC'
**In '''server''', assuming the basic config above, type 'localhost'. '''Save Changes'''.
**Scroll to the bottom of the '''Cache administration''' page you were returned to.
**Under '''Stores used when no mapping is present''' click '''Edit Mappings'''.
**In the '''Application''' drop down select your caches name. '''Save Changes'''.
* Profit

More details can be found in the main [https://docs.moodle.org/310/en/Caching#Memcached Caching documentaion].

==How much RAM should I allocate to MUC?==
Less then you probably think! The default on most Memcached deployments is
64MB and this is probably '''more''' than enough for a pretty standard Moodle
install. As a real world example, checking a live site with ~6000 individual user
logins, over the last 24 hours was using 11MB of Memcached MUC (Moodle 2.8 with 26 additional
plugins).

Most importantly if you decide to implement an in memory cache like Memcached then monitor and understand its use in '''your''' deployment as this can vary wildly.

==I'm already using Memcached for sessions, can I just reuse that?==
Nope, afraid not. If the MUC purges so will sessions, all your users will be
logged out. That does not stop you using two memcached instances, one for
sessions and one MUC. An example of how to do this can be found [https://moopi.mrverrall.co.uk/course/view.php?id=4#section-5 here].

==I have a cluster of servers, <further question here>?==

You are probably beyond the target audience of this FAQ in terms of your system
administration foo.

==What is that little grey triangle?==
[[File:muc-triangle.png|thumb|300px]]
This happens when the default Application Cache does not support a requirement
of one or more of the '''cache definitions'''. Do not panic, it is not important.

For example, of the default application caches only '''Event Invalidation''' is not supported
by Memcached.

Event Invalidation requires '''Data Guarantee''' which ensures data exists in the
cache once it is put there. It is '''never''' cleaned up to free space or because
it has not been recently used. Because (as discussed above/below?) Memcached
evicts objects form it's cache it cannot be used Event Invalidation.

The Event Invalidation cache is used to ENSURE events are handled correctly,
i.e. the objects exist when they are created and don't exist '''only''' when they are purged,
this may not occur if the cache object vanishes unexpectedly as may be the case with Memcached.

So Event Invalidation will just carry on using the file-system cache (or
whatever else you tell it too).

==Where can I find more documentation on setting up the MUC?==
There is some great documemntaion on this site, the [https://docs.moodle.org/310/en/Caching Caching] page is probably your best place to start.

If you are further interested in the nuts and bolts of the caching system, e.g. cache features (ttl, data guarantee, etc) the [https://github.com/moodle/moodle/blob/master/cache/README.md developers api] is a good place to look.

MUC FAQ

2015-10-06T13:38:49Z

Mrverrall: /* Where can I find more documentation on setting up the MUC? */

{{Performance}}

The Moodle Unified Cache (MUC) on initial inspection can appear to be a complex
off-putting beast, and this can lead to it either being ignored or, as is
often the case, poorly configured.

Here is what you need to know (so you can ignore [https://docs.moodle.org/310/en/Caching the rest]).

==What is the MUC?==

The MUC is a cache, a cache is a store of data which is easier/faster to
retrieve than if it came from it's source. It saves (computing) effort and makes Moodle
faster.

==Should I be using the MUC?==

Yes, and if you are using Moodle 2.4 or above you are already using the MUC.

If your site is already running fine then consider '''not changing anything''' as "[https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize premature optimization is the root of all evil]".

By default MUC uses the file system to store it's cached objects, this already speeds thing up greatly than if there was no MUC at all. By further configuring the MUC we are just trying to make it faster.

==What is wrong with the default file-system MUC?==

Not much at all, but the MUCs performance is dependant on the read/write speed of it's storage medium.

Typically disks are slow but safe (persistent) storage. MUC data does not need to kept safe
as it can always be regenerated so it can afford to be kept somewhere fast yet volatile, like RAM.

==How can I make MUC faster?==

Using a RAM based cache is the best way to make the MUC fast and there a few tools we can use for this, such as, tmpfs, Memcached, APC,
Redis and overtime probably more... A good place to start if you are unsure of any specific requirements is Memcached as it is common, well tested, fast and easy to deploy.

==How do I deploy Memcached==

This is by no means exhaustive, and will vary depending on your OS etc. But for simplicities sake...

* Install Memcached in a way compatible with your operating system e.g. in Debian/Ubuntu
apt-get install memcached
* Confiure Memcached, or at least become aware of it's default setup, e.g.
** 64MB of RAM allocation
** Runs on port 11211
* Make sure your PHP has the required support, e.g. in Debian/Ubuntu
apt-get install php5-memcached
* In Moodle go to
**'Site administration > Plugins > Caching > Configuration'
**Under '''Installed cache stores''' you should see Memcached and an '''Add instance''' action. Click '''Add Instance'''.
**Give the store a name, i like 'Memcached_MUC'
**In '''server''', assuming the basic config above, type 'localhost'. '''Save Changes'''.
**Scroll to the bottom of the '''Cache administration''' page you were returned to.
**Under '''Stores used when no mapping is present''' click '''Edit Mappings'''.
**In the '''Application''' drop down select your caches name. '''Save Changes'''.
* Profit

More details can be found in the main [https://docs.moodle.org/310/en/Caching#Memcached Caching documentaion].

==How much RAM should I allocate to MUC?==
Less then you probably think! The default on most Memcached deployments is
64MB and this is probably '''more''' than enough for a pretty standard Moodle
install. As a real world example, checking a live site with ~6000 individual user
logins, over the last 24 hours was using 11MB of Memcached MUC (Moodle 2.8 with 26 additional
plugins).

Most importantly if you decide to implement an in memory cache like Memcached then monitor and understand its use in '''your''' deployment as this can vary wildly.

==I'm already using Memcached for sessions, can I just reuse that?==
Nope, afraid not. If the MUC purges so will sessions, all your users will be
logged out. That does not stop you using two memcached instances, one for
sessions and one MUC. An example of how to do this can be found [https://moopi.mrverrall.co.uk/course/view.php?id=4#section-5 here].

==I have a cluster of servers, <further question here>?==

You are probably beyond the target audience of this FAQ in terms of your system
administration foo.

==What is that little grey triangle?==
[[File:muc-triangle.png|thumb|300px]]
This happens when the default Application Cache does not support a requirement
of one or more of the '''cache definitions'''. Do not panic, it is not important.

For example, of the default application caches only '''Event Invalidation''' is not supported
by Memcached.

Event Invalidation requires '''Data Guarantee''' which ensures data exists in the
cache once it is put there. It is '''never''' cleaned up to free space or because
it has not been recently used. Because (as discussed above/below?) Memcached
evicts objects form it's cache it cannot be used Event Invalidation.

The Event Invalidation cache is used to ENSURE events are handled correctly,
i.e. the objects exist when they are created and don't exist '''only''' when they are purged,
this may not occur if the cache object vanishes unexpectedly as may be the case with Memcached.

So Event Invalidation will just carry on using the file-system cache (or
whatever else you tell it too).

==Where can I find more documentation on setting up the MUC?==
There is some great documemntaion on this site, the [https://docs.moodle.org/310/en/Caching Caching] page is probably your best place to start.

If you are further interested in the nuts and bolts of the caching system, e.g. cache features (ttl, data guarantee, etc) the [https://github.com/moodle/moodle/blob/master/cache/README.md developers api] is a good place to start.

MUC FAQ

2015-10-06T13:38:10Z

Mrverrall: /* What is that little grey triangle? */

{{Performance}}

The Moodle Unified Cache (MUC) on initial inspection can appear to be a complex
off-putting beast, and this can lead to it either being ignored or, as is
often the case, poorly configured.

Here is what you need to know (so you can ignore [https://docs.moodle.org/310/en/Caching the rest]).

==What is the MUC?==

The MUC is a cache, a cache is a store of data which is easier/faster to
retrieve than if it came from it's source. It saves (computing) effort and makes Moodle
faster.

==Should I be using the MUC?==

Yes, and if you are using Moodle 2.4 or above you are already using the MUC.

If your site is already running fine then consider '''not changing anything''' as "[https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize premature optimization is the root of all evil]".

By default MUC uses the file system to store it's cached objects, this already speeds thing up greatly than if there was no MUC at all. By further configuring the MUC we are just trying to make it faster.

==What is wrong with the default file-system MUC?==

Not much at all, but the MUCs performance is dependant on the read/write speed of it's storage medium.

Typically disks are slow but safe (persistent) storage. MUC data does not need to kept safe
as it can always be regenerated so it can afford to be kept somewhere fast yet volatile, like RAM.

==How can I make MUC faster?==

Using a RAM based cache is the best way to make the MUC fast and there a few tools we can use for this, such as, tmpfs, Memcached, APC,
Redis and overtime probably more... A good place to start if you are unsure of any specific requirements is Memcached as it is common, well tested, fast and easy to deploy.

==How do I deploy Memcached==

This is by no means exhaustive, and will vary depending on your OS etc. But for simplicities sake...

* Install Memcached in a way compatible with your operating system e.g. in Debian/Ubuntu
apt-get install memcached
* Confiure Memcached, or at least become aware of it's default setup, e.g.
** 64MB of RAM allocation
** Runs on port 11211
* Make sure your PHP has the required support, e.g. in Debian/Ubuntu
apt-get install php5-memcached
* In Moodle go to
**'Site administration > Plugins > Caching > Configuration'
**Under '''Installed cache stores''' you should see Memcached and an '''Add instance''' action. Click '''Add Instance'''.
**Give the store a name, i like 'Memcached_MUC'
**In '''server''', assuming the basic config above, type 'localhost'. '''Save Changes'''.
**Scroll to the bottom of the '''Cache administration''' page you were returned to.
**Under '''Stores used when no mapping is present''' click '''Edit Mappings'''.
**In the '''Application''' drop down select your caches name. '''Save Changes'''.
* Profit

More details can be found in the main [https://docs.moodle.org/310/en/Caching#Memcached Caching documentaion].

==How much RAM should I allocate to MUC?==
Less then you probably think! The default on most Memcached deployments is
64MB and this is probably '''more''' than enough for a pretty standard Moodle
install. As a real world example, checking a live site with ~6000 individual user
logins, over the last 24 hours was using 11MB of Memcached MUC (Moodle 2.8 with 26 additional
plugins).

Most importantly if you decide to implement an in memory cache like Memcached then monitor and understand its use in '''your''' deployment as this can vary wildly.

==I'm already using Memcached for sessions, can I just reuse that?==
Nope, afraid not. If the MUC purges so will sessions, all your users will be
logged out. That does not stop you using two memcached instances, one for
sessions and one MUC. An example of how to do this can be found [https://moopi.mrverrall.co.uk/course/view.php?id=4#section-5 here].

==I have a cluster of servers, <further question here>?==

You are probably beyond the target audience of this FAQ in terms of your system
administration foo.

==What is that little grey triangle?==
[[File:muc-triangle.png|thumb|300px]]
This happens when the default Application Cache does not support a requirement
of one or more of the '''cache definitions'''. Do not panic, it is not important.

For example, of the default application caches only '''Event Invalidation''' is not supported
by Memcached.

Event Invalidation requires '''Data Guarantee''' which ensures data exists in the
cache once it is put there. It is '''never''' cleaned up to free space or because
it has not been recently used. Because (as discussed above/below?) Memcached
evicts objects form it's cache it cannot be used Event Invalidation.

The Event Invalidation cache is used to ENSURE events are handled correctly,
i.e. the objects exist when they are created and don't exist '''only''' when they are purged,
this may not occur if the cache object vanishes unexpectedly as may be the case with Memcached.

So Event Invalidation will just carry on using the file-system cache (or
whatever else you tell it too).

==Where can I find more documentation on setting up the MUC?==
There is some great documemntaion on this site, the [https://docs.moodle.org/310/en/Caching Caching] page is probably your best place to start.

If you are further interested in the nuts and bolts of teh caching system, e.g. cache features (ttl, data guarantee, etc) the [https://github.com/moodle/moodle/blob/master/cache/README.md developers api] is a good place to start.

MUC FAQ

2015-10-06T13:36:38Z

Mrverrall: /* How can I make MUC faster? */

{{Performance}}

The Moodle Unified Cache (MUC) on initial inspection can appear to be a complex
off-putting beast, and this can lead to it either being ignored or, as is
often the case, poorly configured.

Here is what you need to know (so you can ignore [https://docs.moodle.org/310/en/Caching the rest]).

==What is the MUC?==

The MUC is a cache, a cache is a store of data which is easier/faster to
retrieve than if it came from it's source. It saves (computing) effort and makes Moodle
faster.

==Should I be using the MUC?==

Yes, and if you are using Moodle 2.4 or above you are already using the MUC.

If your site is already running fine then consider '''not changing anything''' as "[https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize premature optimization is the root of all evil]".

By default MUC uses the file system to store it's cached objects, this already speeds thing up greatly than if there was no MUC at all. By further configuring the MUC we are just trying to make it faster.

==What is wrong with the default file-system MUC?==

Not much at all, but the MUCs performance is dependant on the read/write speed of it's storage medium.

Typically disks are slow but safe (persistent) storage. MUC data does not need to kept safe
as it can always be regenerated so it can afford to be kept somewhere fast yet volatile, like RAM.

==How can I make MUC faster?==

Using a RAM based cache is the best way to make the MUC fast and there a few tools we can use for this, such as, tmpfs, Memcached, APC,
Redis and overtime probably more... A good place to start if you are unsure of any specific requirements is Memcached as it is common, well tested, fast and easy to deploy.

==How do I deploy Memcached==

This is by no means exhaustive, and will vary depending on your OS etc. But for simplicities sake...

* Install Memcached in a way compatible with your operating system e.g. in Debian/Ubuntu
apt-get install memcached
* Confiure Memcached, or at least become aware of it's default setup, e.g.
** 64MB of RAM allocation
** Runs on port 11211
* Make sure your PHP has the required support, e.g. in Debian/Ubuntu
apt-get install php5-memcached
* In Moodle go to
**'Site administration > Plugins > Caching > Configuration'
**Under '''Installed cache stores''' you should see Memcached and an '''Add instance''' action. Click '''Add Instance'''.
**Give the store a name, i like 'Memcached_MUC'
**In '''server''', assuming the basic config above, type 'localhost'. '''Save Changes'''.
**Scroll to the bottom of the '''Cache administration''' page you were returned to.
**Under '''Stores used when no mapping is present''' click '''Edit Mappings'''.
**In the '''Application''' drop down select your caches name. '''Save Changes'''.
* Profit

More details can be found in the main [https://docs.moodle.org/310/en/Caching#Memcached Caching documentaion].

==How much RAM should I allocate to MUC?==
Less then you probably think! The default on most Memcached deployments is
64MB and this is probably '''more''' than enough for a pretty standard Moodle
install. As a real world example, checking a live site with ~6000 individual user
logins, over the last 24 hours was using 11MB of Memcached MUC (Moodle 2.8 with 26 additional
plugins).

Most importantly if you decide to implement an in memory cache like Memcached then monitor and understand its use in '''your''' deployment as this can vary wildly.

==I'm already using Memcached for sessions, can I just reuse that?==
Nope, afraid not. If the MUC purges so will sessions, all your users will be
logged out. That does not stop you using two memcached instances, one for
sessions and one MUC. An example of how to do this can be found [https://moopi.mrverrall.co.uk/course/view.php?id=4#section-5 here].

==I have a cluster of servers, <further question here>?==

You are probably beyond the target audience of this FAQ in terms of your system
administration foo.

==What is that little grey triangle?==
[[File:muc-triangle.png|thumb|300px]]
This happens when the default Application Cache does not support a requirement
of one or more of the '''cache definitions'''. Do not panic, it is not important.

For example, of the default application caches only '''Event Invalidation''' is not supported
by Memcached.

Event Invalidation requires '''Data Guarantee''' which ensures data exists in the
cache once it is put there. It is '''never'''cleaned up to free space or because
it has not been recently used. Because (as discussed above/below?) Memcached
evicts objects form it's cache it cannot be used Event Invalidation.

The Event Invalidation cache is used to ENSURE events are handled correctly,
i.e. the objects exist when they are created and don't exist '''only''' when they are purged,
this may not occur if the cache object vanishes unexpectedly as may be the case with Memcached.

So Event Invalidation will just carry on using the file-system cache (or
whatever else you tell it too).

==Where can I find more documentation on setting up the MUC?==
There is some great documemntaion on this site, the [https://docs.moodle.org/310/en/Caching Caching] page is probably your best place to start.

If you are further interested in the nuts and bolts of teh caching system, e.g. cache features (ttl, data guarantee, etc) the [https://github.com/moodle/moodle/blob/master/cache/README.md developers api] is a good place to start.

MUC FAQ

2015-10-06T13:07:15Z

Mrverrall: /* What is that little grey triangle? */

{{Performance}}

The Moodle Unified Cache (MUC) on initial inspection can appear to be a complex
off-putting beast, and this can lead to it either being ignored or, as is
often the case, poorly configured.

Here is what you need to know (so you can ignore [https://docs.moodle.org/310/en/Caching the rest]).

==What is the MUC?==

The MUC is a cache, a cache is a store of data which is easier/faster to
retrieve than if it came from it's source. It saves (computing) effort and makes Moodle
faster.

==Should I be using the MUC?==

Yes, and if you are using Moodle 2.4 or above you are already using the MUC.

If your site is already running fine then consider '''not changing anything''' as "[https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize premature optimization is the root of all evil]".

By default MUC uses the file system to store it's cached objects, this already speeds thing up greatly than if there was no MUC at all. By further configuring the MUC we are just trying to make it faster.

==What is wrong with the default file-system MUC?==

Not much at all, but the MUCs performance is dependant on the read/write speed of it's storage medium.

Typically disks are slow but safe (persistent) storage. MUC data does not need to kept safe
as it can always be regenerated so it can afford to be kept somewhere fast yet volatile, like RAM.

==How can I make MUC faster?==

Using a RAM based cache is the best way to make the MUC fast and there a few tools we can use for this, such as, tmpfs, Memcached, APC,
Redis and overtime probably more... I good place to start if you are unsure of any specific requirements is Memcached as it is common, well tested, fast and easy to deploy.

==How do I deploy Memcached==

This is by no means exhaustive, and will vary depending on your OS etc. But for simplicities sake...

* Install Memcached in a way compatible with your operating system e.g. in Debian/Ubuntu
apt-get install memcached
* Confiure Memcached, or at least become aware of it's default setup, e.g.
** 64MB of RAM allocation
** Runs on port 11211
* Make sure your PHP has the required support, e.g. in Debian/Ubuntu
apt-get install php5-memcached
* In Moodle go to
**'Site administration > Plugins > Caching > Configuration'
**Under '''Installed cache stores''' you should see Memcached and an '''Add instance''' action. Click '''Add Instance'''.
**Give the store a name, i like 'Memcached_MUC'
**In '''server''', assuming the basic config above, type 'localhost'. '''Save Changes'''.
**Scroll to the bottom of the '''Cache administration''' page you were returned to.
**Under '''Stores used when no mapping is present''' click '''Edit Mappings'''.
**In the '''Application''' drop down select your caches name. '''Save Changes'''.
* Profit

More details can be found in the main [https://docs.moodle.org/310/en/Caching#Memcached Caching documentaion].

==How much RAM should I allocate to MUC?==
Less then you probably think! The default on most Memcached deployments is
64MB and this is probably '''more''' than enough for a pretty standard Moodle
install. As a real world example, checking a live site with ~6000 individual user
logins, over the last 24 hours was using 11MB of Memcached MUC (Moodle 2.8 with 26 additional
plugins).

Most importantly if you decide to implement an in memory cache like Memcached then monitor and understand its use in '''your''' deployment as this can vary wildly.

==I'm already using Memcached for sessions, can I just reuse that?==
Nope, afraid not. If the MUC purges so will sessions, all your users will be
logged out. That does not stop you using two memcached instances, one for
sessions and one MUC. An example of how to do this can be found [https://moopi.mrverrall.co.uk/course/view.php?id=4#section-5 here].

==I have a cluster of servers, <further question here>?==

You are probably beyond the target audience of this FAQ in terms of your system
administration foo.

==What is that little grey triangle?==
[[File:muc-triangle.png|thumb|300px]]
This happens when the default Application Cache does not support a requirement
of one or more of the '''cache definitions'''. Do not panic, it is not important.

For example, of the default application caches only '''Event Invalidation''' is not supported
by Memcached.

Event Invalidation requires '''Data Guarantee''' which ensures data exists in the
cache once it is put there. It is '''never'''cleaned up to free space or because
it has not been recently used. Because (as discussed above/below?) Memcached
evicts objects form it's cache it cannot be used Event Invalidation.

The Event Invalidation cache is used to ENSURE events are handled correctly,
i.e. the objects exist when they are created and don't exist '''only''' when they are purged,
this may not occur if the cache object vanishes unexpectedly as may be the case with Memcached.

So Event Invalidation will just carry on using the file-system cache (or
whatever else you tell it too).

==Where can I find more documentation on setting up the MUC?==
There is some great documemntaion on this site, the [https://docs.moodle.org/310/en/Caching Caching] page is probably your best place to start.

If you are further interested in the nuts and bolts of teh caching system, e.g. cache features (ttl, data guarantee, etc) the [https://github.com/moodle/moodle/blob/master/cache/README.md developers api] is a good place to start.

File:muc-triangle.png

2015-10-06T13:05:42Z

Mrverrall: That little grey triangle when your default MUC mapping is not compatible with one or more of the cache definitions.

That little grey triangle when your default MUC mapping is not compatible with one or more of the cache definitions.

MUC FAQ

2015-10-06T12:59:59Z

Mrverrall: /* How much RAM should I allocate to MUC? */

{{Performance}}

The Moodle Unified Cache (MUC) on initial inspection can appear to be a complex
off-putting beast, and this can lead to it either being ignored or, as is
often the case, poorly configured.

Here is what you need to know (so you can ignore [https://docs.moodle.org/310/en/Caching the rest]).

==What is the MUC?==

The MUC is a cache, a cache is a store of data which is easier/faster to
retrieve than if it came from it's source. It saves (computing) effort and makes Moodle
faster.

==Should I be using the MUC?==

Yes, and if you are using Moodle 2.4 or above you are already using the MUC.

If your site is already running fine then consider '''not changing anything''' as "[https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize premature optimization is the root of all evil]".

By default MUC uses the file system to store it's cached objects, this already speeds thing up greatly than if there was no MUC at all. By further configuring the MUC we are just trying to make it faster.

==What is wrong with the default file-system MUC?==

Not much at all, but the MUCs performance is dependant on the read/write speed of it's storage medium.

Typically disks are slow but safe (persistent) storage. MUC data does not need to kept safe
as it can always be regenerated so it can afford to be kept somewhere fast yet volatile, like RAM.

==How can I make MUC faster?==

Using a RAM based cache is the best way to make the MUC fast and there a few tools we can use for this, such as, tmpfs, Memcached, APC,
Redis and overtime probably more... I good place to start if you are unsure of any specific requirements is Memcached as it is common, well tested, fast and easy to deploy.

==How do I deploy Memcached==

This is by no means exhaustive, and will vary depending on your OS etc. But for simplicities sake...

* Install Memcached in a way compatible with your operating system e.g. in Debian/Ubuntu
apt-get install memcached
* Confiure Memcached, or at least become aware of it's default setup, e.g.
** 64MB of RAM allocation
** Runs on port 11211
* Make sure your PHP has the required support, e.g. in Debian/Ubuntu
apt-get install php5-memcached
* In Moodle go to
**'Site administration > Plugins > Caching > Configuration'
**Under '''Installed cache stores''' you should see Memcached and an '''Add instance''' action. Click '''Add Instance'''.
**Give the store a name, i like 'Memcached_MUC'
**In '''server''', assuming the basic config above, type 'localhost'. '''Save Changes'''.
**Scroll to the bottom of the '''Cache administration''' page you were returned to.
**Under '''Stores used when no mapping is present''' click '''Edit Mappings'''.
**In the '''Application''' drop down select your caches name. '''Save Changes'''.
* Profit

More details can be found in the main [https://docs.moodle.org/310/en/Caching#Memcached Caching documentaion].

==How much RAM should I allocate to MUC?==
Less then you probably think! The default on most Memcached deployments is
64MB and this is probably '''more''' than enough for a pretty standard Moodle
install. As a real world example, checking a live site with ~6000 individual user
logins, over the last 24 hours was using 11MB of Memcached MUC (Moodle 2.8 with 26 additional
plugins).

Most importantly if you decide to implement an in memory cache like Memcached then monitor and understand its use in '''your''' deployment as this can vary wildly.

==I'm already using Memcached for sessions, can I just reuse that?==
Nope, afraid not. If the MUC purges so will sessions, all your users will be
logged out. That does not stop you using two memcached instances, one for
sessions and one MUC. An example of how to do this can be found [https://moopi.mrverrall.co.uk/course/view.php?id=4#section-5 here].

==I have a cluster of servers, <further question here>?==

You are probably beyond the target audience of this FAQ in terms of your system
administration foo.

==What is that little grey triangle?==

This happens when the default Application Cache does not support a requirement
of one or more of the '''cache definitions'''. Do not panic, it is not important.

For example, of the default application caches only '''Event Invalidation''' is not supported
by Memcached.

Event Invalidation requires '''Data Guarantee''' which ensures data exists in the
cache once it is put there. It is '''never'''cleaned up to free space or because
it has not been recently used. Because (as discussed above/below?) Memcached
evicts objects form it's cache it cannot be used Event Invalidation.

The Event Invalidation cache is used to ENSURE events are handled correctly,
i.e. the objects exist when they are created and don't exist '''only''' when they are purged,
this may not occur if the cache object vanishes unexpectedly as may be the case with Memcached.

So Event Invalidation will just carry on using the file-system cache (or
whatever else you tell it too).

==Where can I find more documentation on setting up the MUC?==
There is some great documemntaion on this site, the [https://docs.moodle.org/310/en/Caching Caching] page is probably your best place to start.

If you are further interested in the nuts and bolts of teh caching system, e.g. cache features (ttl, data guarantee, etc) the [https://github.com/moodle/moodle/blob/master/cache/README.md developers api] is a good place to start.

MUC FAQ

2015-10-06T12:57:48Z

Mrverrall: /* What is wrong with the default file-system MUC? */

{{Performance}}

The Moodle Unified Cache (MUC) on initial inspection can appear to be a complex
off-putting beast, and this can lead to it either being ignored or, as is
often the case, poorly configured.

Here is what you need to know (so you can ignore [https://docs.moodle.org/310/en/Caching the rest]).

==What is the MUC?==

The MUC is a cache, a cache is a store of data which is easier/faster to
retrieve than if it came from it's source. It saves (computing) effort and makes Moodle
faster.

==Should I be using the MUC?==

Yes, and if you are using Moodle 2.4 or above you are already using the MUC.

If your site is already running fine then consider '''not changing anything''' as "[https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize premature optimization is the root of all evil]".

By default MUC uses the file system to store it's cached objects, this already speeds thing up greatly than if there was no MUC at all. By further configuring the MUC we are just trying to make it faster.

==What is wrong with the default file-system MUC?==

Not much at all, but the MUCs performance is dependant on the read/write speed of it's storage medium.

Typically disks are slow but safe (persistent) storage. MUC data does not need to kept safe
as it can always be regenerated so it can afford to be kept somewhere fast yet volatile, like RAM.

==How can I make MUC faster?==

Using a RAM based cache is the best way to make the MUC fast and there a few tools we can use for this, such as, tmpfs, Memcached, APC,
Redis and overtime probably more... I good place to start if you are unsure of any specific requirements is Memcached as it is common, well tested, fast and easy to deploy.

==How do I deploy Memcached==

This is by no means exhaustive, and will vary depending on your OS etc. But for simplicities sake...

* Install Memcached in a way compatible with your operating system e.g. in Debian/Ubuntu
apt-get install memcached
* Confiure Memcached, or at least become aware of it's default setup, e.g.
** 64MB of RAM allocation
** Runs on port 11211
* Make sure your PHP has the required support, e.g. in Debian/Ubuntu
apt-get install php5-memcached
* In Moodle go to
**'Site administration > Plugins > Caching > Configuration'
**Under '''Installed cache stores''' you should see Memcached and an '''Add instance''' action. Click '''Add Instance'''.
**Give the store a name, i like 'Memcached_MUC'
**In '''server''', assuming the basic config above, type 'localhost'. '''Save Changes'''.
**Scroll to the bottom of the '''Cache administration''' page you were returned to.
**Under '''Stores used when no mapping is present''' click '''Edit Mappings'''.
**In the '''Application''' drop down select your caches name. '''Save Changes'''.
* Profit

More details can be found in the main [https://docs.moodle.org/310/en/Caching#Memcached Caching documentaion].

==How much RAM should I allocate to MUC?==
Less then you probably think! The default on most Memcached deployments is
64MB and this is probably '''more''' than enough for a pretty standard Moodle
install. As a real world example, checking a live site with ~6000 individual user
logins, over the last 24 hours was using 11MB of Memcached MUC (Moodle 2.8 with 26 additional
plugins).

==I'm already using Memcached for sessions, can I just reuse that?==
Nope, afraid not. If the MUC purges so will sessions, all your users will be
logged out. That does not stop you using two memcached instances, one for
sessions and one MUC. An example of how to do this can be found [https://moopi.mrverrall.co.uk/course/view.php?id=4#section-5 here].

==I have a cluster of servers, <further question here>?==

You are probably beyond the target audience of this FAQ in terms of your system
administration foo.

==What is that little grey triangle?==

This happens when the default Application Cache does not support a requirement
of one or more of the '''cache definitions'''. Do not panic, it is not important.

For example, of the default application caches only '''Event Invalidation''' is not supported
by Memcached.

Event Invalidation requires '''Data Guarantee''' which ensures data exists in the
cache once it is put there. It is '''never'''cleaned up to free space or because
it has not been recently used. Because (as discussed above/below?) Memcached
evicts objects form it's cache it cannot be used Event Invalidation.

The Event Invalidation cache is used to ENSURE events are handled correctly,
i.e. the objects exist when they are created and don't exist '''only''' when they are purged,
this may not occur if the cache object vanishes unexpectedly as may be the case with Memcached.

So Event Invalidation will just carry on using the file-system cache (or
whatever else you tell it too).

==Where can I find more documentation on setting up the MUC?==
There is some great documemntaion on this site, the [https://docs.moodle.org/310/en/Caching Caching] page is probably your best place to start.

If you are further interested in the nuts and bolts of teh caching system, e.g. cache features (ttl, data guarantee, etc) the [https://github.com/moodle/moodle/blob/master/cache/README.md developers api] is a good place to start.

MUC FAQ

2015-10-06T12:56:46Z

Mrverrall: /* Should I be using the MUC? */

{{Performance}}

The Moodle Unified Cache (MUC) on initial inspection can appear to be a complex
off-putting beast, and this can lead to it either being ignored or, as is
often the case, poorly configured.

Here is what you need to know (so you can ignore [https://docs.moodle.org/310/en/Caching the rest]).

==What is the MUC?==

The MUC is a cache, a cache is a store of data which is easier/faster to
retrieve than if it came from it's source. It saves (computing) effort and makes Moodle
faster.

==Should I be using the MUC?==

Yes, and if you are using Moodle 2.4 or above you are already using the MUC.

If your site is already running fine then consider '''not changing anything''' as "[https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize premature optimization is the root of all evil]".

By default MUC uses the file system to store it's cached objects, this already speeds thing up greatly than if there was no MUC at all. By further configuring the MUC we are just trying to make it faster.

==What is wrong with the default file-system MUC?==

The MUCs performance is dependant on the read/write speed of it's storage
medium.

Typically disks are slow but safe (persistent) storage. MUC data does not need to kept safe
as it can always be regenerated so it can afford to be kept somewhere fast vet volatile, like RAM.

==How can I make MUC faster?==

Using a RAM based cache is the best way to make the MUC fast and there a few tools we can use for this, such as, tmpfs, Memcached, APC,
Redis and overtime probably more... I good place to start if you are unsure of any specific requirements is Memcached as it is common, well tested, fast and easy to deploy.

==How do I deploy Memcached==

This is by no means exhaustive, and will vary depending on your OS etc. But for simplicities sake...

* Install Memcached in a way compatible with your operating system e.g. in Debian/Ubuntu
apt-get install memcached
* Confiure Memcached, or at least become aware of it's default setup, e.g.
** 64MB of RAM allocation
** Runs on port 11211
* Make sure your PHP has the required support, e.g. in Debian/Ubuntu
apt-get install php5-memcached
* In Moodle go to
**'Site administration > Plugins > Caching > Configuration'
**Under '''Installed cache stores''' you should see Memcached and an '''Add instance''' action. Click '''Add Instance'''.
**Give the store a name, i like 'Memcached_MUC'
**In '''server''', assuming the basic config above, type 'localhost'. '''Save Changes'''.
**Scroll to the bottom of the '''Cache administration''' page you were returned to.
**Under '''Stores used when no mapping is present''' click '''Edit Mappings'''.
**In the '''Application''' drop down select your caches name. '''Save Changes'''.
* Profit

More details can be found in the main [https://docs.moodle.org/310/en/Caching#Memcached Caching documentaion].

==How much RAM should I allocate to MUC?==
Less then you probably think! The default on most Memcached deployments is
64MB and this is probably '''more''' than enough for a pretty standard Moodle
install. As a real world example, checking a live site with ~6000 individual user
logins, over the last 24 hours was using 11MB of Memcached MUC (Moodle 2.8 with 26 additional
plugins).

==I'm already using Memcached for sessions, can I just reuse that?==
Nope, afraid not. If the MUC purges so will sessions, all your users will be
logged out. That does not stop you using two memcached instances, one for
sessions and one MUC. An example of how to do this can be found [https://moopi.mrverrall.co.uk/course/view.php?id=4#section-5 here].

==I have a cluster of servers, <further question here>?==

You are probably beyond the target audience of this FAQ in terms of your system
administration foo.

==What is that little grey triangle?==

This happens when the default Application Cache does not support a requirement
of one or more of the '''cache definitions'''. Do not panic, it is not important.

For example, of the default application caches only '''Event Invalidation''' is not supported
by Memcached.

Event Invalidation requires '''Data Guarantee''' which ensures data exists in the
cache once it is put there. It is '''never'''cleaned up to free space or because
it has not been recently used. Because (as discussed above/below?) Memcached
evicts objects form it's cache it cannot be used Event Invalidation.

The Event Invalidation cache is used to ENSURE events are handled correctly,
i.e. the objects exist when they are created and don't exist '''only''' when they are purged,
this may not occur if the cache object vanishes unexpectedly as may be the case with Memcached.

So Event Invalidation will just carry on using the file-system cache (or
whatever else you tell it too).

==Where can I find more documentation on setting up the MUC?==
There is some great documemntaion on this site, the [https://docs.moodle.org/310/en/Caching Caching] page is probably your best place to start.

If you are further interested in the nuts and bolts of teh caching system, e.g. cache features (ttl, data guarantee, etc) the [https://github.com/moodle/moodle/blob/master/cache/README.md developers api] is a good place to start.

Template:Performance

2015-10-06T12:47:30Z

Mrverrall:

<div class="navtrail">[[Main page]] ► [[Managing a Moodle site]] ► [[Performance]] ► [[{{PAGENAME}}]]</div>
<div class="sideblock right" style="width: 14em;">
<div class="header">[[Performance]]</div>
<div class="content">
*[[Performance recommendations]]
*[[Performance settings]]
*[[Performance overview]]
*[[Caching]]
*[[Performance FAQ]]
*[[MUC FAQ]]
</div>
</div>

<includeonly>[[Category:Performance]]</includeonly>
<noinclude>This template will categorize articles that include it into [[:Category:Performance]].</noinclude>

Talk:MUC FAQ

2015-10-06T12:43:55Z

Mrverrall: Created page with "If you feel other questions could be well addressed here, either add them to the FAQ if you have the answers, or leave a comment here if you have just the question."

If you feel other questions could be well addressed here, either add them to the FAQ if you have the answers, or leave a comment here if you have just the question.

MUC FAQ

2015-10-06T12:41:59Z

Mrverrall: /* How do I deploy Memcached */

{{Performance}}

The Moodle Unified Cache (MUC) on initial inspection can appear to be a complex
off-putting beast, and this can lead to it either being ignored or, as is
often the case, poorly configured.

Here is what you need to know (so you can ignore [https://docs.moodle.org/310/en/Caching the rest]).

==What is the MUC?==

The MUC is a cache, a cache is a store of data which is easier/faster to
retrieve than if it came from it's source. It saves (computing) effort and makes Moodle
faster.

==Should I be using the MUC?==

Yes, and if you are using Moodle 2.4 or above you are already using the MUC.

By default MUC uses the file system to store it's cached objects, this already
speeds thing up greatly than if there was no MUC at all. By further
configuring the MUC we are just trying to make it faster.

==What is wrong with the default file-system MUC?==

The MUCs performance is dependant on the read/write speed of it's storage
medium.

Typically disks are slow but safe (persistent) storage. MUC data does not need to kept safe
as it can always be regenerated so it can afford to be kept somewhere fast vet volatile, like RAM.

==How can I make MUC faster?==

Using a RAM based cache is the best way to make the MUC fast and there a few tools we can use for this, such as, tmpfs, Memcached, APC,
Redis and overtime probably more... I good place to start if you are unsure of any specific requirements is Memcached as it is common, well tested, fast and easy to deploy.

==How do I deploy Memcached==

This is by no means exhaustive, and will vary depending on your OS etc. But for simplicities sake...

* Install Memcached in a way compatible with your operating system e.g. in Debian/Ubuntu
apt-get install memcached
* Confiure Memcached, or at least become aware of it's default setup, e.g.
** 64MB of RAM allocation
** Runs on port 11211
* Make sure your PHP has the required support, e.g. in Debian/Ubuntu
apt-get install php5-memcached
* In Moodle go to
**'Site administration > Plugins > Caching > Configuration'
**Under '''Installed cache stores''' you should see Memcached and an '''Add instance''' action. Click '''Add Instance'''.
**Give the store a name, i like 'Memcached_MUC'
**In '''server''', assuming the basic config above, type 'localhost'. '''Save Changes'''.
**Scroll to the bottom of the '''Cache administration''' page you were returned to.
**Under '''Stores used when no mapping is present''' click '''Edit Mappings'''.
**In the '''Application''' drop down select your caches name. '''Save Changes'''.
* Profit

More details can be found in the main [https://docs.moodle.org/310/en/Caching#Memcached Caching documentaion].

==How much RAM should I allocate to MUC?==
Less then you probably think! The default on most Memcached deployments is
64MB and this is probably '''more''' than enough for a pretty standard Moodle
install. As a real world example, checking a live site with ~6000 individual user
logins, over the last 24 hours was using 11MB of Memcached MUC (Moodle 2.8 with 26 additional
plugins).

==I'm already using Memcached for sessions, can I just reuse that?==
Nope, afraid not. If the MUC purges so will sessions, all your users will be
logged out. That does not stop you using two memcached instances, one for
sessions and one MUC. An example of how to do this can be found [https://moopi.mrverrall.co.uk/course/view.php?id=4#section-5 here].

==I have a cluster of servers, <further question here>?==

You are probably beyond the target audience of this FAQ in terms of your system
administration foo.

==What is that little grey triangle?==

This happens when the default Application Cache does not support a requirement
of one or more of the '''cache definitions'''. Do not panic, it is not important.

For example, of the default application caches only '''Event Invalidation''' is not supported
by Memcached.

Event Invalidation requires '''Data Guarantee''' which ensures data exists in the
cache once it is put there. It is '''never'''cleaned up to free space or because
it has not been recently used. Because (as discussed above/below?) Memcached
evicts objects form it's cache it cannot be used Event Invalidation.

The Event Invalidation cache is used to ENSURE events are handled correctly,
i.e. the objects exist when they are created and don't exist '''only''' when they are purged,
this may not occur if the cache object vanishes unexpectedly as may be the case with Memcached.

So Event Invalidation will just carry on using the file-system cache (or
whatever else you tell it too).

==Where can I find more documentation on setting up the MUC?==
There is some great documemntaion on this site, the [https://docs.moodle.org/310/en/Caching Caching] page is probably your best place to start.

If you are further interested in the nuts and bolts of teh caching system, e.g. cache features (ttl, data guarantee, etc) the [https://github.com/moodle/moodle/blob/master/cache/README.md developers api] is a good place to start.

Performance

2015-10-06T12:36:57Z

Mrverrall:

{{Managing a Moodle site}}
*[[Performance recommendations]]
*[[Performance settings]]
*[[Performance overview]]
*[[Caching]]
*[[How to check your database for corruption]]

==See also==
*[[Performance FAQ]]
*[[MUC FAQ]]

[[Category:Performance]]

[[de:Geschwindigkeit]]
[[es:Desempeño]]

MUC FAQ

2015-10-06T12:35:16Z

Mrverrall: /* What is that little grey triangle? */

{{Performance}}

The Moodle Unified Cache (MUC) on initial inspection can appear to be a complex
off-putting beast, and this can lead to it either being ignored or, as is
often the case, poorly configured.

Here is what you need to know (so you can ignore [https://docs.moodle.org/310/en/Caching the rest]).

==What is the MUC?==

The MUC is a cache, a cache is a store of data which is easier/faster to
retrieve than if it came from it's source. It saves (computing) effort and makes Moodle
faster.

==Should I be using the MUC?==

Yes, and if you are using Moodle 2.4 or above you are already using the MUC.

By default MUC uses the file system to store it's cached objects, this already
speeds thing up greatly than if there was no MUC at all. By further
configuring the MUC we are just trying to make it faster.

==What is wrong with the default file-system MUC?==

The MUCs performance is dependant on the read/write speed of it's storage
medium.

Typically disks are slow but safe (persistent) storage. MUC data does not need to kept safe
as it can always be regenerated so it can afford to be kept somewhere fast vet volatile, like RAM.

==How can I make MUC faster?==

Using a RAM based cache is the best way to make the MUC fast and there a few tools we can use for this, such as, tmpfs, Memcached, APC,
Redis and overtime probably more... I good place to start if you are unsure of any specific requirements is Memcached as it is common, well tested, fast and easy to deploy.

==How do I deploy Memcached==

This is by no means exhaustive, and will vary depending on your OS etc. But for simplicities sake...

* Install Memcached in a way compatible with your operating system e.g. in Debian/Ubuntu
apt-get install memcached
* Confiure Memcached, or at least become aware of it's default setup, e.g.
** 64MB of RAM allocation
** Runs on port 11211
* Make sure your PHP has the required support, e.g. in Debian/Ubuntu
apt-get install php5-memcached
* In Moodle go to
**'Site administration > Plugins > Caching > Configuration'
**Under '''Installed cache stores''' you should see Memcached and an '''Add instance''' action. Click '''Add Instance'''.
**Give the store a name, i like 'Memcached_MUC'
**In '''server''', assuming the basic config above, type 'localhost'. '''Save Changes'''.
**Scroll to the bottom of the '''Cache administration''' page you were returned to.
**Under '''Stores used when no mapping is present''' click '''Edit Mappings'''.
**In the '''Application''' drop down select your caches name. '''Save Changes'''.
* Profit

==How much RAM should I allocate to MUC?==
Less then you probably think! The default on most Memcached deployments is
64MB and this is probably '''more''' than enough for a pretty standard Moodle
install. As a real world example, checking a live site with ~6000 individual user
logins, over the last 24 hours was using 11MB of Memcached MUC (Moodle 2.8 with 26 additional
plugins).

==I'm already using Memcached for sessions, can I just reuse that?==
Nope, afraid not. If the MUC purges so will sessions, all your users will be
logged out. That does not stop you using two memcached instances, one for
sessions and one MUC. An example of how to do this can be found [https://moopi.mrverrall.co.uk/course/view.php?id=4#section-5 here].

==I have a cluster of servers, <further question here>?==

You are probably beyond the target audience of this FAQ in terms of your system
administration foo.

==What is that little grey triangle?==

This happens when the default Application Cache does not support a requirement
of one or more of the '''cache definitions'''. Do not panic, it is not important.

For example, of the default application caches only '''Event Invalidation''' is not supported
by Memcached.

Event Invalidation requires '''Data Guarantee''' which ensures data exists in the
cache once it is put there. It is '''never'''cleaned up to free space or because
it has not been recently used. Because (as discussed above/below?) Memcached
evicts objects form it's cache it cannot be used Event Invalidation.

The Event Invalidation cache is used to ENSURE events are handled correctly,
i.e. the objects exist when they are created and don't exist '''only''' when they are purged,
this may not occur if the cache object vanishes unexpectedly as may be the case with Memcached.

So Event Invalidation will just carry on using the file-system cache (or
whatever else you tell it too).

==Where can I find more documentation on setting up the MUC?==
There is some great documemntaion on this site, the [https://docs.moodle.org/310/en/Caching Caching] page is probably your best place to start.

If you are further interested in the nuts and bolts of teh caching system, e.g. cache features (ttl, data guarantee, etc) the [https://github.com/moodle/moodle/blob/master/cache/README.md developers api] is a good place to start.

MUC FAQ

2015-10-06T12:30:34Z

Mrverrall:

{{Performance}}

The Moodle Unified Cache (MUC) on initial inspection can appear to be a complex
off-putting beast, and this can lead to it either being ignored or, as is
often the case, poorly configured.

Here is what you need to know (so you can ignore [https://docs.moodle.org/310/en/Caching the rest]).

==What is the MUC?==

The MUC is a cache, a cache is a store of data which is easier/faster to
retrieve than if it came from it's source. It saves (computing) effort and makes Moodle
faster.

==Should I be using the MUC?==

Yes, and if you are using Moodle 2.4 or above you are already using the MUC.

By default MUC uses the file system to store it's cached objects, this already
speeds thing up greatly than if there was no MUC at all. By further
configuring the MUC we are just trying to make it faster.

==What is wrong with the default file-system MUC?==

The MUCs performance is dependant on the read/write speed of it's storage
medium.

Typically disks are slow but safe (persistent) storage. MUC data does not need to kept safe
as it can always be regenerated so it can afford to be kept somewhere fast vet volatile, like RAM.

==How can I make MUC faster?==

Using a RAM based cache is the best way to make the MUC fast and there a few tools we can use for this, such as, tmpfs, Memcached, APC,
Redis and overtime probably more... I good place to start if you are unsure of any specific requirements is Memcached as it is common, well tested, fast and easy to deploy.

==How do I deploy Memcached==

This is by no means exhaustive, and will vary depending on your OS etc. But for simplicities sake...

* Install Memcached in a way compatible with your operating system e.g. in Debian/Ubuntu
apt-get install memcached
* Confiure Memcached, or at least become aware of it's default setup, e.g.
** 64MB of RAM allocation
** Runs on port 11211
* Make sure your PHP has the required support, e.g. in Debian/Ubuntu
apt-get install php5-memcached
* In Moodle go to
**'Site administration > Plugins > Caching > Configuration'
**Under '''Installed cache stores''' you should see Memcached and an '''Add instance''' action. Click '''Add Instance'''.
**Give the store a name, i like 'Memcached_MUC'
**In '''server''', assuming the basic config above, type 'localhost'. '''Save Changes'''.
**Scroll to the bottom of the '''Cache administration''' page you were returned to.
**Under '''Stores used when no mapping is present''' click '''Edit Mappings'''.
**In the '''Application''' drop down select your caches name. '''Save Changes'''.
* Profit

==How much RAM should I allocate to MUC?==
Less then you probably think! The default on most Memcached deployments is
64MB and this is probably '''more''' than enough for a pretty standard Moodle
install. As a real world example, checking a live site with ~6000 individual user
logins, over the last 24 hours was using 11MB of Memcached MUC (Moodle 2.8 with 26 additional
plugins).

==I'm already using Memcached for sessions, can I just reuse that?==
Nope, afraid not. If the MUC purges so will sessions, all your users will be
logged out. That does not stop you using two memcached instances, one for
sessions and one MUC. An example of how to do this can be found [https://moopi.mrverrall.co.uk/course/view.php?id=4#section-5 here].

==I have a cluster of servers, <further question here>?==

You are probably beyond the target audience of this FAQ in terms of your system
administration foo.

==What is that little grey triangle?==

This happens when the default Application Cache does not support a requirement
of one or more of the '''cache definitions'''. Do not panic, it is not important.

For example, of the default application caches only '''Event Invalidation''' is not supported
by Memcached.

Event Invalidation requires '''Data Guarantee''' which ensures data exists in the
cache once it is put there. It is *never* cleaned up to free space or because
it has not been recently used. Because (as discussed above/below?) Memcached
evicts objects form it's cache it cannot be used Event Invalidation.

The Event Invalidation cache is used to ENSURE events are handled correctly,
i.e. the objects exist when they are created and don't only when they are purged,
this may not occur if the cache object vanishes unexpectedly.

So Event Invalidation will just carry on using the file-system cache (or
whatever else you tell it too).

==Where can I find more documentation on setting up the MUC?==
There is some great documemntaion on this site, the [https://docs.moodle.org/310/en/Caching Caching] page is probably your best place to start.

If you are further interested in the nuts and bolts of teh caching system, e.g. cache features (ttl, data guarantee, etc) the [https://github.com/moodle/moodle/blob/master/cache/README.md developers api] is a good place to start.

MUC FAQ

2015-10-06T12:17:47Z

Mrverrall: Created page with "{{MUC FAQ}} The Moodle Unified Cache (MUC) on initial inspection can appear to be a complex off-putting beast, and this can lead to it either being ignored or, as is often t..."

{{MUC FAQ}}

The Moodle Unified Cache (MUC) on initial inspection can appear to be a complex
off-putting beast, and this can lead to it either being ignored or, as is
often the case, poorly configured.

Here is what you need to know (so you can ignore [https://docs.moodle.org/310/en/Caching the rest]).

==What is the MUC?==

The MUC is a cache, a cache is a store of data which is easier/faster to
retrieve than if it came from it's source. It saves (computing) effort and makes Moodle
faster.

==Should I be using the MUC?==

Yes, and if you are using Moodle 2.4 or above you are already using the MUC.

By default MUC uses the file system to store it's cached objects, this already
speeds thing up greatly than if there was no MUC at all. By further
configuring the MUC we are just trying to make it faster.

==What is wrong with the default file-system MUC?==

The MUCs performance is dependant on the read/write speed of it's storage
medium.

Typically disks are slow but safe (persistent) storage. MUC data does not need to kept safe
as it can always be regenerated so it can afford to be kept somewhere fast vet volatile, like RAM.

==How can I make MUC faster?==

Using a RAM based cache is the best way to make the MUC fast and there a few tools we can use for this, such as, tmpfs, Memcached, APC,
Redis and overtime probably more... I good place to start if you are unsure of any specific requirements is Memcached as it is common, well tested, fast and easy to deploy.

==How do I deploy Memcached==

This is by no means exhaustive, and will vary depending on your OS etc. But for simplicities sake...

* Install Memcached in a way compatible with your operating system e.g. in Debian/Ubuntu
apt-get install memcached
* Confiure Memcached, or at least become aware of it's default setup, e.g.
** 64MB of RAM allocation
** Runs on port 11211
* Make sure your PHP has the required support, e.g. in Debian/Ubuntu
apt-get install php5-memcached
* In Moodle go to
**'Site administration > Plugins > Caching > Configuration'
**Under '''Installed cache stores''' you should see Memcached and an '''Add instance''' action. Click '''Add Instance'''.
**Give the store a name, i like 'Memcached_MUC'
**In '''server''', assuming the basic config above, type 'localhost'. '''Save Changes'''.
**Scroll to the bottom of the '''Cache administration''' page you were returned to.
**Under '''Stores used when no mapping is present''' click '''Edit Mappings'''.
**In the '''Application''' drop down select your caches name. '''Save Changes'''.
* Profit

==How much RAM should I allocate to MUC?==
Less then you probably think! The default on most Memcached deployments is
64MB and this is probably '''more''' than enough for a pretty standard Moodle
install. As a real world example, checking a live site with ~6000 individual user
logins, over the last 24 hours was using 11MB of Memcached MUC (Moodle 2.8 with 26 additional
plugins).

==I'm already using Memcached for sessions, can I just reuse that?==
Nope, afraid not. If the MUC purges so will sessions, all your users will be
logged out. That does not stop you using two memcached instances, one for
sessions and one MUC. An example of how to do this can be found [https://moopi.mrverrall.co.uk/course/view.php?id=4#section-5 here].

==I have a cluster of servers, <further question here>?==

You are probably beyond the target audience of this FAQ in terms of your system
administration foo.

==What is that little grey triangle?==

This happens when the default Application Cache does not support a requirement
of one or more of the '''cache definitions'''. Do not panic, it is not important.

For example, of the default application caches only '''Event Invalidation''' is not supported
by Memcached.

Event Invalidation requires '''Data Guarantee''' which ensures data exists in the
cache once it is put there. It is *never* cleaned up to free space or because
it has not been recently used. Because (as discussed above/below?) Memcached
evicts objects form it's cache it cannot be used Event Invalidation.

The Event Invalidation cache is used to ENSURE events are handled correctly,
i.e. the objects exist when they are created and don't only when they are purged,
this may not occur if the cache object vanishes unexpectedly.

So Event Invalidation will just carry on using the file-system cache (or
whatever else you tell it too).

==Where can I find more documentation on setting up the MUC?==
There is some great documemntaion on this site, the [https://docs.moodle.org/310/en/Caching Caching] page is probably your best place to start.

If you are further interested in the nuts and bolts of teh caching system, e.g. cache features (ttl, data guarantee, etc) the [https://github.com/moodle/moodle/blob/master/cache/README.md developers api] is a good place to start.

Talk:Nginx

2015-10-05T15:54:45Z

Mrverrall:

I've removed the lines from this page instructing users to set the php configuration parameter [http://php.net/manual/en/ini.core.php#ini.cgi.fix-pathinfo cgi.fix-pathinfo]=0

This line is included in a lot of on-line how-to guides for Nginx/PHP and is explained as a security restriction, see, [https://nealpoole.com/blog/2011/04/setting-up-php-fastcgi-and-nginx-dont-trust-the-tutorials-check-your-configuration/ here] and [http://serverfault.com/questions/627903/is-the-php-option-cgi-fix-pathinfo-really-dangerous-with-nginx-php-fpm here]

In summary, within the context of Nginx and php-fpm the best(?) way to handle potential PATH_INFO vulnerabilities as described in those articles is to use the default behaviour of php-fpm, i.e. within,

'''/etc/php5/fpm/pool.d/www.conf''' (debianised)
security.limit_extensions = .php

Either way will work just fine, but this is one step less with no real down sides...

'''Links:'''<br>
https://nealpoole.com/blog/2011/04/setting-up-php-fastcgi-and-nginx-dont-trust-the-tutorials-check-your-configuration/<br>
http://serverfault.com/questions/627903/is-the-php-option-cgi-fix-pathinfo-really-dangerous-with-nginx-php-fpm

Nginx

2015-09-04T09:30:17Z

Mrverrall: /* PHP-FPM */

{{Installing Moodle}}[[Nginx]] [engine x] is an HTTP and reverse proxy server, as well as a mail proxy server, written by Igor Sysoev. The nginx project started with a strong focus on high concurrency, high performance and low memory usage. It is licensed under the 2-clause BSD-like license and it runs on Linux, BSD variants, Mac OS X, Solaris, AIX, HP-UX, as well as on other *nix flavours. It also has a proof of concept port for Microsoft Windows.

''The following is community-contributed documentation on Nginx configuration. Amendments and additions are welcome.''

== Nginx configuration ==

=== PHP-FPM ===

Nginx is usually configured to interface with PHP via [http://php.net/manual/en/install.fpm.php php-fpm]. This is both fast and robust.

PHP-FPM's default behaviour for pools is usually to restrict the execution of scripts to a specific extension, i.e. .php. You should ensure that this behaviour is configured within your particular package/distribution, e.g. for debian,

'''/etc/php5/fpm/pool.d/www.conf'''
security.limit_extensions = .php

=== Nginx ===

Add the following 'slash arguments' compatible (see [[Using slash arguments]]) 'location' block to your vhosts 'server' configuration in your nginx configuration.

'''nginx.conf location:'''
<pre>
location ~ [^/]\.php(/|$) {
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_index index.php;
fastcgi_pass 127.0.0.1:9000 (or your php-fpm socket);
include fastcgi_params;
fastcgi_param PATH_INFO $fastcgi_path_info;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
</pre>

===== XSendfile aka X-Accel-Redirect =====

Setting Moodle and Nginx to use XSendfile functionality is a big win as it frees PHP from delivering files allowing Nginx to do what it does best, i.e. deliver files.

Enable xsendfile for Nginx in Moodles config.php, this is documented in the config-dist.php, a minimal configuration look like this,
<pre>
$CFG->xsendfile = 'X-Accel-Redirect';
$CFG->xsendfilealiases = array(
'/dataroot/' => $CFG->dataroot
);
</pre>
Accompany this with a matching 'location' block in your nginx server configuration.
<pre>
location /dataroot/ {
internal;
alias <full_moodledata_path>; # ensure the path ends with /
}
</pre>
The definition of 'internal' here is '''critical''' as it prevents client access to your dataroot.

== See also ==

* Real <tt>PATH_INFO</tt> support:
** https://moodle.org/mod/forum/discuss.php?d=278916
** https://moodle.org/mod/forum/discuss.php?d=307388
* Internal rewriting to the HTTP GET <tt>file</tt> parameter:
** https://docs.moodle.org/dev/Install_Moodle_On_Ubuntu_with_Nginx/PHP-fpm
** https://moodle.org/mod/forum/discuss.php?d=83445

[[Category:Installation]]

[[es:Nginx]]

Talk:Nginx

2015-09-04T09:25:30Z

Mrverrall: Created page with "I've removed the lines from this page instructing users to set the php configuration parameter [http://php.net/manual/en/ini.core.php#ini.cgi.fix-pathinfo cgi.fix-pathinfo]=0..."

I've removed the lines from this page instructing users to set the php configuration parameter [http://php.net/manual/en/ini.core.php#ini.cgi.fix-pathinfo cgi.fix-pathinfo]=0

This line is included in a lot of on-line how-to guides for Nginx/PHP and is explained as a security restriction, see, [https://nealpoole.com/blog/2011/04/setting-up-php-fastcgi-and-nginx-dont-trust-the-tutorials-check-your-configuration/ here] and [http://serverfault.com/questions/627903/is-the-php-option-cgi-fix-pathinfo-really-dangerous-with-nginx-php-fpm here]

In summary, within the context of Nginx and php-fpm the best(?) way to handle potential PATH_INFO vulnerabilities as described in those articles is to use the default behaviour of php-fpm, i.e. within,

'''/etc/php5/fpm/pool.d/www.conf''' (debianised)
security.limit_extensions = .php

'''Links:'''<br>
https://nealpoole.com/blog/2011/04/setting-up-php-fastcgi-and-nginx-dont-trust-the-tutorials-check-your-configuration/<br>
http://serverfault.com/questions/627903/is-the-php-option-cgi-fix-pathinfo-really-dangerous-with-nginx-php-fpm

Nginx

2015-08-25T13:55:57Z

Mrverrall:

Nginx

2015-08-25T13:53:49Z

Mrverrall: I don't believe cgi.fix_pathinfo=0 is necessary.

Nginx

2015-08-25T13:50:37Z

Mrverrall: Fixed spellings

{{Installing Moodle}}[[Nginx]] [engine x] is an HTTP and reverse proxy server, as well as a mail proxy server, written by Igor Sysoev. The nginx project started with a strong focus on high concurrency, high performance and low memory usage. It is licensed under the 2-clause BSD-like license and it runs on Linux, BSD variants, Mac OS X, Solaris, AIX, HP-UX, as well as on other *nix flavours. It also has a proof of concept port for Microsoft Windows.

''The following is community-contributed documentation on Nginx configuration. Amendments and additions are welcome.''

== Nginx configuration ==

=== PHP-FPM ===

Nginx is usually configured to interface with PHP via [http://php.net/manual/en/install.fpm.php php-fpm]. This is both fast and robust.

==== php.ini ====
Typically the php-fpm daemon with have it's own php.ini e.g. in debian it is /etc/php5/fpm/php.ini. The following setting is required,

'''php.ini'''
<pre>
cgi.fix_pathinfo=0
</pre>

=== Nginx ===

====Slasharguments====
Add the following 'slash arguments' compatible (see [[Using slash arguments]]) 'location' block to your vhosts 'server' configuration in your nginx configuration.

'''nginx.conf location:'''
<pre>
location ~ [^/]\.php(/|$) {
# NOTE: You should have "cgi.fix_pathinfo = 0;" in php.ini
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_index index.php;
fastcgi_pass 127.0.0.1:9000 (or your php-fpm socket);
include fastcgi_params;
fastcgi_param PATH_INFO $fastcgi_path_info;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

}
</pre>

==== XSendfile aka X-Accel-Redirect ====

Setting Moodle and Nginx to use XSendfile functionality is a big win as it frees PHP from delivering files allowing Nginx to do what it does best, i.e. deliver files.

Enable xsendfile for Nginx in Moodles config.php, this is documented in the config-dist.php, a minimal configuration look like this,
<pre>
$CFG->xsendfile = 'X-Accel-Redirect';
$CFG->xsendfilealiases = array(
'/dataroot/' => $CFG->dataroot
);
</pre>
Accompany this with a matching 'location' block in your nginx server configuration.
<pre>
location /dataroot/ {
internal;
alias <full_moodledata_path>; #make sure the path ends with /
}
</pre>
The definition of 'internal' here is important as it prevents client access to your dataroot.

== See also ==

* Real <tt>PATH_INFO</tt> support:
** https://moodle.org/mod/forum/discuss.php?d=278916
** https://moodle.org/mod/forum/discuss.php?d=307388
* Internal rewriting to the HTTP GET <tt>file</tt> parameter:
** https://docs.moodle.org/dev/Install_Moodle_On_Ubuntu_with_Nginx/PHP-fpm
** https://moodle.org/mod/forum/discuss.php?d=83445

[[Category:Installation]]

[[es:Nginx]]

Nginx

2015-05-28T15:58:22Z

Mrverrall: /* server configuration */

{{Installing Moodle}}[[Nginx]] [engine x] is an HTTP and reverse proxy server, as well as a mail proxy server, written by Igor Sysoev. The nginx project started with a strong focus on high concurrency, high performance and low memory usage. It is licensed under the 2-clause BSD-like license and it runs on Linux, BSD variants, Mac OS X, Solaris, AIX, HP-UX, as well as on other *nix flavors. It also has a proof of concept port for Microsoft Windows.

''The following is community-contributed documentation on Nginx configuration. Amendmends and additions are welcome.''

== Nginx configuration ==

=== PHP-FPM ===

Nginx is usually configured to interface with PHP via [http://php.net/manual/en/install.fpm.php php-fpm]. This is both fast and robust.

==== php.ini ====
Typically the php-fpm daemon with have it's own php.ini e.g. in debian it is /etc/php5/fpm/php.ini. The following setting is required,

'''php.ini'''
<pre>
cgi.fix_pathinfo=0
</pre>

=== Nginx ===

====Slasharguments====
Add the following 'slash arguments' compatible (see [[Using slash arguments]]) 'location' block to your vhosts 'server' configuration in your nginx configuration.

'''nginx.conf location:'''
<pre>
location ~ [^/]\.php(/|$) {
# NOTE: You should have "cgi.fix_pathinfo = 0;" in php.ini
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_index index.php;
fastcgi_pass 127.0.0.1:9000 (or your php-fpm socket);
include fastcgi_params;
fastcgi_param PATH_INFO $fastcgi_path_info;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

}
</pre>

==== XSendfile aka X-Accel-Redirect ====

Setting Moodle and Nginx to use XSendfile functionality is a big win as it frees PHP from delivering files allowing Nginx to do what it does best, i.e. deliver files.

Enable xsendfile for Nginx in Moodles config.php, this is documented in the config-dist.php, a minimal configuration look like this,
<pre>
$CFG->xsendfile = 'X-Accel-Redirect';
$CFG->xsendfilealiases = array(
'/dataroot/' => $CFG->dataroot
);
</pre>
Accompany this with a matching 'location' block in your nginx server configuration.
<pre>
location /dataroot/ {
internal;
alias <full_moodledata_path>;
}
</pre>
The definition of 'internal' here is important as it prevents client access to your dataroot.

== See also ==

* Real <tt>PATH_INFO</tt> support:
** https://moodle.org/mod/forum/discuss.php?d=278916
* Internal rewriting to the HTTP GET <tt>file</tt> parameter:
** https://docs.moodle.org/dev/Install_Moodle_On_Ubuntu_with_Nginx/PHP-fpm
** https://moodle.org/mod/forum/discuss.php?d=83445

[[Category:Installation]]

[[es:Nginx]]

Nginx

2015-05-28T15:22:58Z

Mrverrall:

{{Installing Moodle}}[[Nginx]] [engine x] is an HTTP and reverse proxy server, as well as a mail proxy server, written by Igor Sysoev. The nginx project started with a strong focus on high concurrency, high performance and low memory usage. It is licensed under the 2-clause BSD-like license and it runs on Linux, BSD variants, Mac OS X, Solaris, AIX, HP-UX, as well as on other *nix flavors. It also has a proof of concept port for Microsoft Windows.

''The following is community-contributed documentation on Nginx configuration. Amendmends and additions are welcome.''

== Nginx configuration ==

=== PHP-FPM ===

Nginx is usually configured to interface with PHP via [http://php.net/manual/en/install.fpm.php php-fpm]. This is both fast and robust.

==== php.ini ====
Typically the php-fpm daemon with have it's own php.ini e.g. in debian it is /etc/php5/fpm/php.ini. The following setting is required,

'''php.ini'''
<pre>
cgi.fix_pathinfo=0
</pre>

=== Nginx ===

==== server configuration ====
Add the following 'slash arguments' compatible (see [[Using slash arguments]]) 'location' block to your vhosts 'server' configuration in your nginx configuration.

'''nginx.conf location:'''
<pre>
location ~ [^/]\.php(/|$) {
# NOTE: You should have "cgi.fix_pathinfo = 0;" in php.ini
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_index index.php;
fastcgi_pass 127.0.0.1:9000 (or your php-fpm socket);
include fastcgi_params;
fastcgi_param PATH_INFO $fastcgi_path_info;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

}
</pre>

==== XSendfile aka X-Accel-Redirect ====

Setting Moodle and Nginx to use XSendfile functionality is a big win as it frees PHP from delivering files allowing Nginx to do what it does best, i.e. deliver files.

Enable xsendfile for Nginx in Moodles config.php, this is documented in the config-dist.php, a minimal configuration look like this,
<pre>
$CFG->xsendfile = 'X-Accel-Redirect';
$CFG->xsendfilealiases = array(
'/dataroot/' => $CFG->dataroot
);
</pre>
Accompany this with a matching 'location' block in your nginx server configuration.
<pre>
location /dataroot/ {
internal;
alias <full_moodledata_path>;
}
</pre>
The definition of 'internal' here is important as it prevents client access to your dataroot.

== See also ==

* Real <tt>PATH_INFO</tt> support:
** https://moodle.org/mod/forum/discuss.php?d=278916
* Internal rewriting to the HTTP GET <tt>file</tt> parameter:
** https://docs.moodle.org/dev/Install_Moodle_On_Ubuntu_with_Nginx/PHP-fpm
** https://moodle.org/mod/forum/discuss.php?d=83445

[[Category:Installation]]

[[es:Nginx]]

Nginx

2015-05-28T15:14:46Z

Mrverrall: /* Nginx */

{{Installing Moodle}}[[Nginx]] [engine x] is an HTTP and reverse proxy server, as well as a mail proxy server, written by Igor Sysoev. The nginx project started with a strong focus on high concurrency, high performance and low memory usage. It is licensed under the 2-clause BSD-like license and it runs on Linux, BSD variants, Mac OS X, Solaris, AIX, HP-UX, as well as on other *nix flavors. It also has a proof of concept port for Microsoft Windows.

''The following is community-contributed documentation on Nginx configuration. Amendmends and additions are welcome.''

== Nginx configuration ==

=== PHP-FPM ===

Nginx is usually configured to interface with PHP via [http://php.net/manual/en/install.fpm.php php-fpm]. This is both fast and robust.

==== php.ini ====
Typically the php-fpm daemon with have it's own php.ini e.g. in debian it is /etc/php5/fpm/php.ini. The following setting is required,

'''php.ini'''
<pre>
cgi.fix_pathinfo=0
</pre>

=== Nginx ===

==== fcig_params ====
The standard [http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_param fastcgi_params] file included in Nginx is not compatible with moodle; save a new fastcgi_params file with the following parameters,
<pre>
fastcgi_param QUERY_STRING $query_string;
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;

fastcgi_param PATH_INFO $fastcgi_path_info;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

fastcgi_param SCRIPT_NAME $fastcgi_script_name;
fastcgi_param REQUEST_URI $request_uri;
fastcgi_param DOCUMENT_URI $document_uri;
fastcgi_param DOCUMENT_ROOT $document_root;
fastcgi_param SERVER_PROTOCOL $server_protocol;

fastcgi_param GATEWAY_INTERFACE CGI/1.1;
fastcgi_param SERVER_SOFTWARE nginx/$nginx_version;

fastcgi_param REMOTE_ADDR $remote_addr;
fastcgi_param REMOTE_PORT $remote_port;
fastcgi_param SERVER_ADDR $server_addr;
fastcgi_param SERVER_PORT $server_port;
fastcgi_param SERVER_NAME $server_name;

# PHP only, required if PHP was built with --enable-force-cgi-redirect
fastcgi_param REDIRECT_STATUS 200;
</pre>

==== server configuration ====
Add the following 'slash arguments' compatible (see [[Using slash arguments]]) 'location' block to your vhosts 'server' configuration in your nginx configuration.

'''nginx.conf location:'''
<pre>
location ~ [^/]\.php(/|$) {
# NOTE: You should have "cgi.fix_pathinfo = 0;" in php.ini
fastcgi_split_path_info ^(.+\.php)(/.+)$;
include fastcgi_params;
fastcgi_index index.php;
fastcgi_pass 127.0.0.1:9000;
}
</pre>

==== XSendfile aka X-Accel-Redirect ====

Setting Moodle and Nginx to use XSendfile functionality is a big win as it frees PHP from delivering files allowing Nginx to do what it does best, i.e. deliver files.

Enable xsendfile for Nginx in Moodles config.php, this is documented in the config-dist.php, a minimal configuration look like this,
<pre>
$CFG->xsendfile = 'X-Accel-Redirect';
$CFG->xsendfilealiases = array(
'/dataroot/' => $CFG->dataroot
);
</pre>
Accompany this with a matching 'location' block in your nginx server configuration.
<pre>
location /dataroot/ {
internal;
alias <full_moodledata_path>;
}
</pre>
The definition of 'internal' here is important as it prevents client access to your dataroot.

== See also ==

* Real <tt>PATH_INFO</tt> support:
** https://moodle.org/mod/forum/discuss.php?d=278916
* Internal rewriting to the HTTP GET <tt>file</tt> parameter:
** https://docs.moodle.org/dev/Install_Moodle_On_Ubuntu_with_Nginx/PHP-fpm
** https://moodle.org/mod/forum/discuss.php?d=83445

[[Category:Installation]]

[[es:Nginx]]

Nginx

2015-05-28T13:24:37Z

Mrverrall:

{{Installing Moodle}}[[Nginx]] [engine x] is an HTTP and reverse proxy server, as well as a mail proxy server, written by Igor Sysoev. The nginx project started with a strong focus on high concurrency, high performance and low memory usage. It is licensed under the 2-clause BSD-like license and it runs on Linux, BSD variants, Mac OS X, Solaris, AIX, HP-UX, as well as on other *nix flavors. It also has a proof of concept port for Microsoft Windows.

''The following is community-contributed documentation on Nginx configuration. Amendmends and additions are welcome.''

== Nginx configuration ==

=== PHP-FPM ===

Nginx is usually configured to interface with PHP via [http://php.net/manual/en/install.fpm.php php-fpm]. This is both fast and robust.

==== php.ini ====
Typically the php-fpm daemon with have it's own php.ini e.g. in debian it is /etc/php5/fpm/php.ini. The following setting is required,

'''php.ini'''
<pre>
cgi.fix_pathinfo=0
</pre>

=== Nginx ===

==== fcig_params ====
The standard [http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_param fastcgi_params] file included in Nginx is not compatible with moodle; save a new fastcgi_params file with the following parameters,
<pre>
fastcgi_param QUERY_STRING $query_string;
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;

fastcgi_param SCRIPT_NAME $fastcgi_script_name;
fastcgi_param REQUEST_URI $request_uri;
fastcgi_param DOCUMENT_URI $document_uri;
fastcgi_param DOCUMENT_ROOT $document_root;
fastcgi_param SERVER_PROTOCOL $server_protocol;

fastcgi_param GATEWAY_INTERFACE CGI/1.1;
fastcgi_param SERVER_SOFTWARE nginx/$nginx_version;

fastcgi_param REMOTE_ADDR $remote_addr;
fastcgi_param REMOTE_PORT $remote_port;
fastcgi_param SERVER_ADDR $server_addr;
fastcgi_param SERVER_PORT $server_port;
fastcgi_param SERVER_NAME $server_name;

# PHP only, required if PHP was built with --enable-force-cgi-redirect
fastcgi_param REDIRECT_STATUS 200;
</pre>

==== server configuration ====
Add the following 'slash arguments' compatible (see [[Using slash arguments]]) 'location' block to your vhosts 'server' configuration in your nginx configuration.

'''nginx.conf location:'''
<pre>
location ~ [^/]\.php(/|$) {
# NOTE: You should have "cgi.fix_pathinfo = 0;" in php.ini
fastcgi_split_path_info ^(.+\.php)(/.+)$;
include fastcgi_params;
fastcgi_index index.php;
fastcgi_pass 127.0.0.1:9000;
}
</pre>

==== XSendfile aka X-Accel-Redirect ====

Setting Moodle and Nginx to use XSendfile functionality is a big win as it frees PHP from delivering files allowing Nginx to do what it does best, i.e. deliver files.

Enable xsendfile for Nginx in Moodles config.php, this is documented in the config-dist.php, a minimal configuration look like this,
<pre>
$CFG->xsendfile = 'X-Accel-Redirect';
$CFG->xsendfilealiases = array(
'/dataroot/' => $CFG->dataroot
);
</pre>
Accompany this with a matching 'location' block in your nginx server configuration.
<pre>
location /dataroot/ {
internal;
alias <full_moodledata_path>;
}
</pre>
The definition of 'internal' here is important as it prevents client access to your dataroot.

== See also ==

* Real <tt>PATH_INFO</tt> support:
** https://moodle.org/mod/forum/discuss.php?d=278916
* Internal rewriting to the HTTP GET <tt>file</tt> parameter:
** https://docs.moodle.org/dev/Install_Moodle_On_Ubuntu_with_Nginx/PHP-fpm
** https://moodle.org/mod/forum/discuss.php?d=83445

[[Category:Installation]]

[[es:Nginx]]

User talk:Paul Verrall

2015-05-22T09:42:47Z

Mrverrall: Created blank page

User:Paul Verrall

2015-05-22T09:41:33Z

Mrverrall: Created page with "I'm the systems administrator at Lancaster University Network Services. I work a lot with Moodle day to day but mostly on the nuts and bolts of keeping things running smoothly..."

I'm the systems administrator at Lancaster University Network Services. I work a lot with Moodle day to day but mostly on the nuts and bolts of keeping things running smoothly rather than actually logging into a Moodle site.

Asides from being a professional geek I also enjoy craft beers and all types of whisky of which I have many bottles.

I run a small moodle site at [http://moopi.mrverrall.co.uk moopi.mrverrall.co.uk] to try and help dispel the myth that Moodle needs lots of server resources to run effectively.

Nginx

2015-05-21T15:51:34Z

Mrverrall:

{{Installing Moodle}}[[Nginx]] [engine x] is an HTTP and reverse proxy server, as well as a mail proxy server, written by Igor Sysoev. The nginx project started with a strong focus on high concurrency, high performance and low memory usage. It is licensed under the 2-clause BSD-like license and it runs on Linux, BSD variants, Mac OS X, Solaris, AIX, HP-UX, as well as on other *nix flavors. It also has a proof of concept port for Microsoft Windows.

''The following is community-contributed documentation on Nginx configuration. Amendmends and additions are welcome.''

== Nginx configuration ==

=== PHP-FPM ===

Nginx is usually configured to interface with PHP via [http://php.net/manual/en/install.fpm.php php-fpm]. This is both fast and robust.

==== php.ini ====
Typically the php-fpm daemon with have it's own php.ini e.g. in debian it is /etc/php5/fpm/php.ini. The following setting is required,

'''php.ini'''
<pre>
cgi.fix_pathinfo=0
</pre>

=== Nginx ===

==== fcig_params ====
The standard [http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_param fastcgi_params] file included in Nginx is not compatible with moodle; save a new fastcgi_params file with the following parameters,
<pre>
fastcgi_param QUERY_STRING $query_string;
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;

fastcgi_param SCRIPT_NAME $fastcgi_script_name;
fastcgi_param REQUEST_URI $request_uri;
fastcgi_param DOCUMENT_URI $document_uri;
fastcgi_param DOCUMENT_ROOT $document_root;
fastcgi_param SERVER_PROTOCOL $server_protocol;

fastcgi_param GATEWAY_INTERFACE CGI/1.1;
fastcgi_param SERVER_SOFTWARE nginx/$nginx_version;

fastcgi_param REMOTE_ADDR $remote_addr;
fastcgi_param REMOTE_PORT $remote_port;
fastcgi_param SERVER_ADDR $server_addr;
fastcgi_param SERVER_PORT $server_port;
fastcgi_param SERVER_NAME $server_name;

# PHP only, required if PHP was built with --enable-force-cgi-redirect
fastcgi_param REDIRECT_STATUS 200;
</pre>

==== server configuration ====
Add the following 'slash arguments' compatible (see [[Using slash arguments]]) 'location' block to your vhosts 'server' configuration in your nginx configuration.

'''nginx.conf location:'''
<pre>
location ~ [^/]\.php(/|$) {
# NOTE: You should have "cgi.fix_pathinfo = 0;" in php.ini
fastcgi_split_path_info ^(.+\.php)(/.+)$;
include fastcgi_params;
fastcgi_index index.php;
fastcgi_pass 127.0.0.1:9000;
}
</pre>

== See also ==

* https://docs.moodle.org/dev/Install_Moodle_On_Ubuntu_with_Nginx/PHP-fpm
* https://moodle.org/mod/forum/discuss.php?d=83445

[[Category:Installation]]

[[es:Nginx]]

Nginx

2015-05-21T15:26:49Z

Mrverrall: /* Slasharguments */

Upload users

2014-10-15T07:21:52Z

Mrverrall:

{{Accounts}}
An administrator can upload multiple user accounts via text file in ''Administration > Site administration > Users > Accounts > Upload users''.

There are many robust options for uploading information (fields associated with a user) with this method: from enrolling users in multiple courses with course specific [[Roles|roles]] to updating user information in the [[User profile]] to deleting users from the site.

Rather than uploading the text file, it can simply dragged from the desktop and dropped into the upload area, as demonstrated in the screencast [http://youtu.be/6E-TQXTkZB0 Drag and drop new users into Moodle 2.3] (by Mary Cooch).

''Tip:'' It is usually not necessary to upload users in bulk with Upload users. To keep maintenance work down you should first explore forms of authentication that do not require manual maintenance, such as [[External database authentication|connecting to existing external databases]] or letting the users create their own accounts ([[Self enrolment]]). See [[Authentication]] for more information.

[[File:uploadusersnew.png|thumb|500px|center|Initial upload users screen]]

==Upload user process==
Here is an outline of the process:

# Create file for uploading
# Go to ''Administration > Site administration > Users > Accounts > Upload users''
# Add file to upload
# Upload users preview - check settings and default user profile settings
# Upload users preview - click "Upload users"
# Upload users results - shows list of users, exceptions made in upload and summary of number of users
# Upload users results - click "Continue"
# Returns to Upload users screen

==Updating users preview==
There are settings for the kind of Upload user function you want to perform on the "Upload users preview" page.
[[File:Upload users preview 2.0.JPG|thumb|center|Upload users preview in Moodle 2.x]]

===Updating existing accounts===

By default Moodle adds new user accounts and skips existing users lines where the <code>username</code> matches an existing account. Set "Upload Type" to '''Add new and update existing users''', and existing user account will be updated.
*Add all, append number to usernames if needed
*Add new and update existing users
*Update existing users only

'''Warning''': errors updating existing accounts can affect your users badly. Be careful when using the options to update.

===Additional Options===

There are also fields settings to force password change, allow renames, allow deletes, prevent email address duplicates, standardise usernames and select for bulk operations(new users. updated users, all users).

*Standardise usernames - This folds username to lowercase and strips out illegal characters. This is roughly equivalent to:

$username = preg_replace('/[^-\.@_a-z0-9]/', '', $username);

===Set default user values===

You may be able to set default user field values, if the fields were not included in the uploaded file on this page.

==Upload user results ==
After accepting the preview settings by clicking on "Upload users", you should see the the Upload users results screen.
[[File:Upload users results 2.0.JPG|thumb|center|The results screen; everything went well!]]
This screen will show you any exceptions or changes that were made to each user in the upload process. For example if you were updating user information, the updated information will be shown. Or if a user was not added that record will be highlighted.

The screen will summarize how many users were uploaded or updated, indicate the number of weak passwords and the number of errors.

==File formats for upload users file==
The upload users file has fields separated by a comma (or other delimiter) ONLY - no space. The first line contains the valid field names. The rest of the lines (records) contain information about each user.

'':Tip:'' Avoid special characters in field information like quotes or other commas. Test a file with only one record before a large upload. Remember there are other ways to authenticate users on you site or enroll users in a course.

'':Tip:'' You can use a spread sheet program to create the file with the required columns and fields. Then save the file as "CSV (comma delimited)". These files can be opened with simple text editors for verification.

===Valid upload file for testing===
Here is an example of a simple valid upload file:
(Column headers on the first line of the file are only highlighted in bold in this example to distinguish it from the rest of the of the data/user details)

'''username,password,firstname,lastname,email,course1,group1,cohort1'''
jonest,verysecret,Tom,Jones,jonest@someplace.edu,math102,Section 1,year 3
reznort,somesecret,Trent,Reznor,reznort@someplace.edu,math102,Section 3,year 4

===Fields that can be included===
'':Tip:'' We strongly recommend that you test a file that contains fields you proposed to use with one user before attempting a file upload for the first time. http://demo.moodle.net might be a good place to see if your test file works.

*'''Required fields''':
:<p><code>username,firstname,lastname,email</code>
:Validity checks are performed for:
#<code>username</code> can only contain alphabetical '''lowercase''' letters , numbers, hypen '-', underscore '_', period '.', or at-sign '@'
#<code>email</code> is in the form: ''name@example.com'' .</p>

*'''Password field''': "password" field is optional if "Create password if needed" setting is chosen (default).
**If included, values should meet the requirements for the site's [[Site_policies#Password_policy|Password policy]]. To force password change for a particular user, set the password field to <code>changeme</code>.
**If omitted, a password will be generated for each user (during the next Cron job) and welcome e-mails sent out.
**Note: the text for the welcome e-mail is in the language settings. Please refer to this [https://moodle.org/mod/forum/discuss.php?d=210359&parent=917138 forum thread]for details.

*'''Optional fields''': To provide values other than the default include one or more of these
:<p><code>institution,department,city,country,lang,auth,timezone,idnumber,icq,phone1,phone2,address,url,description,mailformat,maildisplay,htmleditor,autosubscribe</code></p>
*'''[[Additional name fields]]'''
*Country- use a country TWO LETTER CODE
*Some fields have a maximum number of characters that are allowed (notably institution should be '''at most 40 characters''' long). See hints below.
*Maildisplay, htmleditor and autosubscribe can be set from an import screen.

*'''Custom profile field names''': (Optional). xxxxx is the real custom user profile field name (i.e. the unique shortname)
:<p><code>profile_field_xxxxx</code></p>
: Create the custom fields BEFORE importing. Use the standard header. The "shortname" for your custom field is xxxxx (NB the shortname must be all lowercase, otherwise won't be recognised). The first record must include "profile_field_xxxxx".

:'''Example''': To create a custom field "genre", you must write a shortname "genre" in the new field, and write "profile_field_genre" in the header of the .csv file.

: For custom profile fields that are a menu, use the corresponding value (new in Moodle 2.3 onwards).

:'''Example''': A custom field 'Department' with one of three values 'HR', 'Marketing' or 'Training'. Just insert one of those three words (e.g. 'Training') as the value for that field.

*'''Special fields''': Used for changing of usernames or deleting of users
:<p><code>oldusername</code>, <code>deleted</code></p>

*'''Enrolment fields''': (Optional):
:<code>course1,type1,role1,group1,enrolperiod1,enrolstatus1,course2,type2,role2,group2,enrolperiod2,enrolstatus2</code> etc.

:* Header fields must have a numeric suffix such that <code>type1</code>,<code>role1</code>,<code>group1</code>,<code>enrolperiod1</code> and <code>enrolstatus1</code> all apply to <code>course1</code> for course<code>1</code> to course<code>n</code>.
:*<code>course</code> is the "shortname" of the course, if present the user will be enrolled in that course.
:* <code>type</code> sets the role to be used for the enrolment. A value of <code>1</code> is default course role, <code>2</code> is legacy Teacher role and <code>3</code> is legacy Non-editing Teacher.
:* <code>role</code> may be used to specify roles directly, using either role short name or id (numeric names of roles are not supported).
:* <code>group</code> may be used to assign users to groups in course, using name or id (numeric group names are not supported)
:* <code>enrolperiod</code> may be used to set the enrolment duration, in days, for each course.
:* <code>enrolstatus</code> can suspend users from a course when set to 1 or left blank for enrolled.

*'''Cohort field''': (Optional):
:<code>cohort1</code>

:Internal cohort id numbers or non-numeric Cohort IDs of existing cohorts must be used; names are not allowed.
*'''mnethostid''' (Optional)

Existing [[MNet]]users can be added to courses, groups or cohorts as below:
#enrolling to courses: username+mnethostid+course required
# adding to group: username+mnethostid+course+group required
#adding to cohort: username+mnethostid+cohort required
#suspending/reviving accounts: username+mnethostid+suspended required
All other operations are ignored. You can not add users, delete them or update them (such as change names or email, profile fields, etc.)

Commas within a field must be encoded as &#44 - the script will decode these back to commas.

For Boolean fields, use <code>0</code> for false and <code>1</code> for true.

To prevent users from receiving a large number of emails from courses or forced subscription forums use the '''maildigest'''. The options for this field are 0 = No digest, 1 = Complete digest and 2 = Digest with just subjects.

==Advanced potentials of Upload user==
===Templates===

''Note: This section needs checking and updating if necessary for Moodle 2.0. Please do so and remove this note when finished.''

The default values are processed as templates in which the following codes are allowed:

* %l - will be replaced by the lastname
* %f - will be replaced by the firstname
* %u - will be replaced by the username
* %% - will be replaced by the %

Between the percent sign (%) and any code letter (l, f or u) the following modifiers are allowed:

* (-) minus sign - the information specified by the code letter will be converted to lowercase
* (+) plus sign - the information specified by the code letter will be converted to UPPERCASE
* (~) tilde sign - the information specified by the code letter will be converted to Title Case
* a decimal number - the information specified by the code letter will be truncated to that many characters

For example, if the firstname is John and the lastname is Doe, the following values will be obtained with the specified templates:

* %l%f = DoeJohn
* %l%1f = DoeJ
* %-l%+f = doeJOHN
* %-f_%-l = john_doe
*<nowiki> http://www.example.com/~%u/</nowiki> results in <nowiki>http://www.example.com/~jdoe/</nowiki> (if the username is jdoe or %-1f%-l)

Template processing is done only on default values, and not on the values retrieved from the CSV file.

In order to create correct Moodle usernames, the username is always converted to lowercase. Moreover, if the "Allow extended characters in usernames" option in the Site policies page is off, characters different to letters, digits, dash (-) and dot (.) are removed. For example if the firstname is John Jr. and the lastname is Doe, the username %-f_%-l will produce john jr._doe when Allow extended characters in usernames is on, and johnjr.doe when off.

When the "New username duplicate handling" setting is set to Append counter, an auto-increment counter will be append to duplicate usernames produced by the template. For example, if the CSV file contains the users named John Doe, Jane Doe and Jenny Doe without explicit usernames, the default username is %-1f%-l and New username duplicate handling is set to Append counter, then the usernames produced will be jdoe, jdoe2 and jdoe3.

===Deleting accounts===

If the <code>deleted</code> field is present, users with value 1 for it will be deleted. In this case, all the fields may be omitted, except for <code>username</code>. After uploading the file, be sure to change the "Upload type" to "Update existing users only" and the "Allow deletes" option to "Yes".

:''Tip:'' A similar field is available for <code>suspended</code>. This enables a user account to be temporarily disabled rather than completely removed.

Deleting and uploading accounts could be done with a single CSV file. For example, the following file will add the user Tom Jones and delete the user reznort:

username,firstname,lastname,deleted
jonest,Tom,Jones,0
reznort,,,1

==Encoding file format==
On the initial Upload user screen, you may select the file encoding format from a pull down list. These include UTF-8 (the default), ASCII, ISO-8859-1 to ISO-8859-11 or any one of over 36 formats.

==Hints==

===Spreadsheet===

If you use a spreadsheet program such as Excel to create your .csv file, check the resulting output in a text editor before you upload it. It is possible to get trailing commas on each line from an empty field if you have added and deleted columns of information prior to saving the final file. Also check the character encoding. A csv file is a simple text file (ASCII or Unicode) that can be used to upload user accounts.

Excel translates passwords that begin with - (minus) or + (plus) as zero. Even when saving as .csv and saying "Yes" to "Keep this format, and leave out any incompatible features." Check for this before uploading, as a zero halts the upload process.

If you use a formula in Excel to create fields (for example, the concatenate function to create a user name), then remember to copy the cells with the formula and use special paste with values checked to make them into an acceptable data for a csv file.

The upload will also fail if you have trailing spaces at the end of your data fields. Often, this can not be removed with a simple Find " " and Replace with "". If information has been copied from web sources than it is possible to include non-breaking spaces which will prevent your upload from being completed correctly. To find these invisible spaces, use the Find and Replace function in Excel. In the find field, hold alt and type 0160. Leave the replace field blank.

===Country===
The country should be written as a two letter code, in capitals. For example, use BE for Belgium or NL for the Netherlands. Using "be" or "nl" as a country code will result in a database error.
:''Tip:'' If you are having trouble working out the two-letter code for a country, you can consult the list of [http://www.iso.org/iso/country_names_and_code_elements country names and code elements] available on the ISO Website. A common error is to use UK for United Kingdom; it should be GB.

===Field size limits===
Some fields have maximum character lengths. Typically the file will import to the preview list screen but not finish the process. Turn on debug to see the fields that are too long. Common fields to cause problems are "Institution" which is limited to 40 characters, and "City", also limited (20 characters). The error will be "User not added - error".

===Time zones===

The entry is case sensitive so Europe/London will work but europe/london will not.

===All fields listed here===
:All the fields that are valid are listed below, except for any custom fields you may have created.
firstname, lastname, username, email, city, country, lang, timezone, mailformat, maildisplay, maildigest, htmleditor, ajax, autosubscribe ,institution, department, idnumber, skype , msn, aim, yahoo, icq, phone1, phone2, address, url, description, descriptionformat, password, auth, oldusername , deleted, suspended, course1, course2, course3, course4

===Enroll users to Cohorts (system groups)===
You can enroll users to any Cohort (system level group) by using only the "username" and the "Cohort ID".
Here is a sample CSV file:

'''username,cohort1'''
teacher1,system-teachers
teacher2,system-teachers
teacher3,system-teachers

Make sure you set "Upload type" to "Update existing users only" (So you are not asked to add firstname, lastname and email fields too)

== See also ==
* [http://youtu.be/PFGLZnuu_JI Adding users by using a CSV in Moodle] MoodleBites video on YouTube
*[[Flat file]] enrolment
* [[User profile fields]] for details of how to include data about custom user profile fields in the upload users file
* [[Upload courses]]

Using Moodle forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=36851 Can I auto enroll from Excel?]
*[http://moodle.org/mod/forum/discuss.php?d=97903 Uploading users to custom roles]
*[http://moodle.org/mod/forum/discuss.php?d=181259 User upload option: standardise usernames]
*[http://moodle.org/mod/forum/discuss.php?d=144569 Matriculacion con flat file csv] - discussion in Spanish

[[fr:Importer des utilisateurs]]
[[ja:ユーザのアップロード]]
[[de:Nutzerliste hochladen]]
[[es:Subir usuarios]]

Upload users

2014-10-14T14:43:39Z

Mrverrall:

{{Accounts}}
An administrator can upload multiple user accounts via text file in ''Administration > Site administration > Users > Accounts > Upload users''.

There are many robust options for uploading information (fields associated with a user) with this method: from enrolling users in multiple courses with course specific [[Roles|roles]] to updating user information in the [[User profile]] to deleting users from the site.

Rather than uploading the text file, it can simply dragged from the desktop and dropped into the upload area, as demonstrated in the screencast [http://youtu.be/6E-TQXTkZB0 Drag and drop new users into Moodle 2.3] (by Mary Cooch).

''Tip:'' It is usually not necessary to upload users in bulk with Upload users. To keep maintenance work down you should first explore forms of authentication that do not require manual maintenance, such as [[External database authentication|connecting to existing external databases]] or letting the users create their own accounts ([[Self enrolment]]). See [[Authentication]] for more information.

[[File:uploadusersnew.png|thumb|500px|center|Initial upload users screen]]

==Upload user process==
Here is an outline of the process:

# Create file for uploading
# Go to ''Administration > Site administration > Users > Accounts > Upload users''
# Add file to upload
# Upload users preview - check settings and default user profile settings
# Upload users preview - click "Upload users"
# Upload users results - shows list of users, exceptions made in upload and summary of number of users
# Upload users results - click "Continue"
# Returns to Upload users screen

==Updating users preview==
There are settings for the kind of Upload user function you want to perform on the "Upload users preview" page.
[[File:Upload users preview 2.0.JPG|thumb|center|Upload users preview in Moodle 2.x]]

===Updating existing accounts===

By default Moodle adds new user accounts and skips existing users lines where the <code>username</code> matches an existing account. Set "Upload Type" to '''Add new and update existing users''', and existing user account will be updated.
*Add all, append number to usernames if needed
*Add new and update existing users
*Update existing users only

'''Warning''': errors updating existing accounts can affect your users badly. Be careful when using the options to update.

===Additional Options===

There are also fields settings to force password change, allow renames, allow deletes, prevent email address duplicates, standardise usernames and select for bulk operations(new users. updated users, all users).

*Standardise usernames - This folds username to lowercase and strips out illegal characters. This is roughly equivalent to:

$username = preg_replace('/[^-\.@_a-z0-9]/', '', $username);

===Set default user values===

You may be able to set default user field values, if the fields were not included in the uploaded file on this page.

==Upload user results ==
After accepting the preview settings by clicking on "Upload users", you should see the the Upload users results screen.
[[File:Upload users results 2.0.JPG|thumb|center|The results screen; everything went well!]]
This screen will show you any exceptions or changes that were made to each user in the upload process. For example if you were updating user information, the updated information will be shown. Or if a user was not added that record will be highlighted.

The screen will summarize how many users were uploaded or updated, indicate the number of weak passwords and the number of errors.

==File formats for upload users file==
The upload users file has fields separated by a comma (or other delimiter) ONLY - no space. The first line contains the valid field names. The rest of the lines (records) contain information about each user.

'':Tip:'' Avoid special characters in field information like quotes or other commas. Test a file with only one record before a large upload. Remember there are other ways to authenticate users on you site or enroll users in a course.

'':Tip:'' You can use a spread sheet program to create the file with the required columns and fields. Then save the file as "CSV (comma delimited)". These files can be opened with simple text editors for verification.

===Valid upload file for testing===
Here is an example of a simple valid upload file:
(Column headers on the first line of the file are only highlighted in bold in this example to distinguish it from the rest of the of the data/user details)

'''username,password,firstname,lastname,email,course1,group1,cohort1'''
jonest,verysecret,Tom,Jones,jonest@someplace.edu,math102,Section 1,year 3
reznort,somesecret,Trent,Reznor,reznort@someplace.edu,math102,Section 3,year 4

===Fields that can be included===
'':Tip:'' We strongly recommend that you test a file that contains fields you proposed to use with one user before attempting a file upload for the first time. http://demo.moodle.net might be a good place to see if your test file works.

*'''Required fields''':
:<p><code>username,firstname,lastname,email</code>
:Validity checks are performed for:
#<code>username</code> can only contain alphabetical '''lowercase''' letters , numbers, hypen '-', underscore '_', period '.', or at-sign '@'
#<code>email</code> is in the form: ''name@example.com'' .</p>

*'''Password field''': "password" field is optional if "Create password if needed" setting is chosen (default).
**If included, values should meet the requirements for the site's [[Site_policies#Password_policy|Password policy]]. To force password change for a particular user, set the password field to <code>changeme</code>.
**If omitted, a password will be generated for each user (during the next Cron job) and welcome e-mails sent out.
**Note: the text for the welcome e-mail is in the language settings. Please refer to this [https://moodle.org/mod/forum/discuss.php?d=210359&parent=917138 forum thread]for details.

*'''Optional fields''': To provide values other than the default include one or more of these
:<p><code>institution,department,city,country,lang,auth,timezone,idnumber,icq,phone1,phone2,address,url,description,mailformat,maildisplay,htmleditor,autosubscribe</code></p>
*'''[[Additional name fields]]'''
*Country- use a country TWO LETTER CODE
*Some fields have a maximum number of characters that are allowed (notably institution should be '''at most 40 characters''' long). See hints below.
*Maildisplay, htmleditor and autosubscribe can be set from an import screen.

*'''Custom profile field names''': (Optional). xxxxx is the real custom user profile field name (i.e. the unique shortname)
:<p><code>profile_field_xxxxx</code></p>
: Create the custom fields BEFORE importing. Use the standard header. The "shortname" for your custom field is xxxxx (NB the shortname must be all lowercase, otherwise won't be recognised). The first record must include "profile_field_xxxxx".

:'''Example''': To create a custom field "genre", you must write a shortname "genre" in the new field, and write "profile_field_genre" in the header of the .csv file.

: For custom profile fields that are a menu, use the corresponding value (new in Moodle 2.3 onwards).

:'''Example''': A custom field 'Department' with one of three values 'HR', 'Marketing' or 'Training'. Just insert one of those three words (e.g. 'Training') as the value for that field.

*'''Special fields''': Used for changing of usernames or deleting of users
:<p><code>oldusername</code>, <code>deleted</code></p>

*'''Enrolment fields''': (Optional):
:<code>course1,type1,role1,group1,enrolperiod1,enrolstatus1,course2,type2,role2,group2,enrolperiod2,enrolstatus2</code> etc.

:* Header fields must have a numeric suffix such that <code>type1</code>,<code>role1</code>,<code>group1</code>,<code>enrolperiod1</code> and <code>enrolstatus1</code> all apply to <code>course1</code> for course<code>1</code> to course<code>n</code>.
:*<code>course</code> is the "shortname" of the course, if present the user will be enrolled in that courses.
:* <code>type</code> sets the role to be used for the enrolment. A value of <code>1</code> is default course role, <code>2</code> is legacy Teacher role and <code>3</code> is legacy Non-editing Teacher.
:* <code>role</code> may be used to specify roles directly, using either role short name or id (numeric names of roles are not supported).
:* <code>group</code> may be used to assign users to groups in course, using name or id (numeric group names are not supported)
:* <code>enrolperiod</code> may be used to set the enrolment duration, in days, for each course.
:* <code>enrolstatus</code> can suspend users from a course when set to 1 or left blank for enrolled.

*'''Cohort field''': (Optional):
:<code>cohort1</code>

:Internal cohort id numbers or non-numeric Cohort IDs of existing cohorts must be used; names are not allowed.
*'''mnethostid''' (Optional)

Existing [[MNet]]users can be added to courses, groups or cohorts as below:
#enrolling to courses: username+mnethostid+course required
# adding to group: username+mnethostid+course+group required
#adding to cohort: username+mnethostid+cohort required
#suspending/reviving accounts: username+mnethostid+suspended required
All other operations are ignored. You can not add users, delete them or update them (such as change names or email, profile fields, etc.)

Commas within a field must be encoded as &#44 - the script will decode these back to commas.

For Boolean fields, use <code>0</code> for false and <code>1</code> for true.

To prevent users from receiving a large number of emails from courses or forced subscription forums use the '''maildigest'''. The options for this field are 0 = No digest, 1 = Complete digest and 2 = Digest with just subjects.

==Advanced potentials of Upload user==
===Templates===

''Note: This section needs checking and updating if necessary for Moodle 2.0. Please do so and remove this note when finished.''

The default values are processed as templates in which the following codes are allowed:

* %l - will be replaced by the lastname
* %f - will be replaced by the firstname
* %u - will be replaced by the username
* %% - will be replaced by the %

Between the percent sign (%) and any code letter (l, f or u) the following modifiers are allowed:

* (-) minus sign - the information specified by the code letter will be converted to lowercase
* (+) plus sign - the information specified by the code letter will be converted to UPPERCASE
* (~) tilde sign - the information specified by the code letter will be converted to Title Case
* a decimal number - the information specified by the code letter will be truncated to that many characters

For example, if the firstname is John and the lastname is Doe, the following values will be obtained with the specified templates:

* %l%f = DoeJohn
* %l%1f = DoeJ
* %-l%+f = doeJOHN
* %-f_%-l = john_doe
*<nowiki> http://www.example.com/~%u/</nowiki> results in <nowiki>http://www.example.com/~jdoe/</nowiki> (if the username is jdoe or %-1f%-l)

Template processing is done only on default values, and not on the values retrieved from the CSV file.

In order to create correct Moodle usernames, the username is always converted to lowercase. Moreover, if the "Allow extended characters in usernames" option in the Site policies page is off, characters different to letters, digits, dash (-) and dot (.) are removed. For example if the firstname is John Jr. and the lastname is Doe, the username %-f_%-l will produce john jr._doe when Allow extended characters in usernames is on, and johnjr.doe when off.

When the "New username duplicate handling" setting is set to Append counter, an auto-increment counter will be append to duplicate usernames produced by the template. For example, if the CSV file contains the users named John Doe, Jane Doe and Jenny Doe without explicit usernames, the default username is %-1f%-l and New username duplicate handling is set to Append counter, then the usernames produced will be jdoe, jdoe2 and jdoe3.

===Deleting accounts===

If the <code>deleted</code> field is present, users with value 1 for it will be deleted. In this case, all the fields may be omitted, except for <code>username</code>. After uploading the file, be sure to change the "Upload type" to "Update existing users only" and the "Allow deletes" option to "Yes".

:''Tip:'' A similar field is available for <code>suspended</code>. This enables a user account to be temporarily disabled rather than completely removed.

Deleting and uploading accounts could be done with a single CSV file. For example, the following file will add the user Tom Jones and delete the user reznort:

username,firstname,lastname,deleted
jonest,Tom,Jones,0
reznort,,,1

==Encoding file format==
On the initial Upload user screen, you may select the file encoding format from a pull down list. These include UTF-8 (the default), ASCII, ISO-8859-1 to ISO-8859-11 or any one of over 36 formats.

==Hints==

===Spreadsheet===

If you use a spreadsheet program such as Excel to create your .csv file, check the resulting output in a text editor before you upload it. It is possible to get trailing commas on each line from an empty field if you have added and deleted columns of information prior to saving the final file. Also check the character encoding. A csv file is a simple text file (ASCII or Unicode) that can be used to upload user accounts.

Excel translates passwords that begin with - (minus) or + (plus) as zero. Even when saving as .csv and saying "Yes" to "Keep this format, and leave out any incompatible features." Check for this before uploading, as a zero halts the upload process.

If you use a formula in Excel to create fields (for example, the concatenate function to create a user name), then remember to copy the cells with the formula and use special paste with values checked to make them into an acceptable data for a csv file.

The upload will also fail if you have trailing spaces at the end of your data fields. Often, this can not be removed with a simple Find " " and Replace with "". If information has been copied from web sources than it is possible to include non-breaking spaces which will prevent your upload from being completed correctly. To find these invisible spaces, use the Find and Replace function in Excel. In the find field, hold alt and type 0160. Leave the replace field blank.

===Country===
The country should be written as a two letter code, in capitals. For example, use BE for Belgium or NL for the Netherlands. Using "be" or "nl" as a country code will result in a database error.
:''Tip:'' If you are having trouble working out the two-letter code for a country, you can consult the list of [http://www.iso.org/iso/country_names_and_code_elements country names and code elements] available on the ISO Website. A common error is to use UK for United Kingdom; it should be GB.

===Field size limits===
Some fields have maximum character lengths. Typically the file will import to the preview list screen but not finish the process. Turn on debug to see the fields that are too long. Common fields to cause problems are "Institution" which is limited to 40 characters, and "City", also limited (20 characters). The error will be "User not added - error".

===Time zones===

The entry is case sensitive so Europe/London will work but europe/london will not.

===All fields listed here===
:All the fields that are valid are listed below, except for any custom fields you may have created.
firstname, lastname, username, email, city, country, lang, timezone, mailformat, maildisplay, maildigest, htmleditor, ajax, autosubscribe ,institution, department, idnumber, skype , msn, aim, yahoo, icq, phone1, phone2, address, url, description, descriptionformat, password, auth, oldusername , deleted, suspended, course1, course2, course3, course4

===Enroll users to Cohorts (system groups)===
You can enroll users to any Cohort (system level group) by using only the "username" and the "Cohort ID".
Here is a sample CSV file:

'''username,cohort1'''
teacher1,system-teachers
teacher2,system-teachers
teacher3,system-teachers

Make sure you set "Upload type" to "Update existing users only" (So you are not asked to add firstname, lastname and email fields too)

== See also ==
* [http://youtu.be/PFGLZnuu_JI Adding users by using a CSV in Moodle] MoodleBites video on YouTube
*[[Flat file]] enrolment
* [[User profile fields]] for details of how to include data about custom user profile fields in the upload users file
* [[Upload courses]]

Using Moodle forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=36851 Can I auto enroll from Excel?]
*[http://moodle.org/mod/forum/discuss.php?d=97903 Uploading users to custom roles]
*[http://moodle.org/mod/forum/discuss.php?d=181259 User upload option: standardise usernames]
*[http://moodle.org/mod/forum/discuss.php?d=144569 Matriculacion con flat file csv] - discussion in Spanish

[[fr:Importer des utilisateurs]]
[[ja:ユーザのアップロード]]
[[de:Nutzerliste hochladen]]
[[es:Subir usuarios]]