View source for System Administrator's Guide/Installing Mahara

<font size="larger">'''<span style="background-color: rgb(192, 192, 192)">Nearby:</span>'''<span style="background-color: rgb(192, 192, 192)"> [[System Administrator's Guide/Upgrading Mahara|Upgrading Mahara]]</span></font>'''<br />'''

This is a guide to installing Mahara. It's mainly targeted at the main platform on which people will install it (Linux with Apache), though [[System Administrator's Guide/Requirements|Mahara can be installed on other platforms]].

Mahara is a web application. This means it's not just an executable file you can download and run. You need a server to put it on (you can use your desktop as a server if you're just trialling it). You'll need to install other software for it to run too - such as the Apache web server and PostgreSQL database system. Another alternative is to use shared hosting - but [[System Administrator's Guide/Requirements#Can I use shared hosting.3f|this isn't as good as having a machine where you can have administrator access]]. If you would still like to install Mahara on shared hosting, a detailed guide with screen shots and video tutorials is available on http://mygreatlearningsite.com/. This guide will show you how to install Mahara via cPanel and is designed for users who don't any previous experience with creating websites or setting up databases.

If you're running Debian/Ubuntu, a lot of the required software (and even Mahara itself) can be installed using <code>apt-get</code>. If you're using some other linux distribution, you may be able to use your distribution specific install tool also.

<div id="section_1">

==Dependencies==

Mahara is mainly designed for use on Linux, using the Apache web server, PostgreSQL database server and PHP. We also support its use with the MySQL database server.

In addition, members of the community have successfully got Mahara running on [[System Administrator's Guide/Installing Mahara/MAC Installation|Mac OSX]] and [[System Administrator's Guide/Installing Mahara/Installing Mahara in Wampserver|Windows]], and have also managed to use [[System Administrator's Guide/Installing Mahara/Mahara on fastcgi%2f%2fnginx|nginx]] instead of Apache. The Mahara developers fix bugs found that prevent running on these platforms, but don't explicitly test them from day to day, so you may have less luck than using a Linux box with Apache.

<div id="section_2">

===Hardware===

* CPU: any modern CPU produced in the last few years is fine, the faster the better naturally. PHP pages are CPU limited, so faster CPUs mean quicker response times.
* Memory: 256MB at an absolute minimum. 1G or more is recommended.
* Disk: This will depend largely on how much disk quota you want each user to have. For a site of 1000 users, each with a 250M quota, you might need 50G to start with.

See the [[System Administrator's Guide/Scalability|scalability article]] for more information on the hardware required, and how you can calculate how much you need. One modern entry-level server will handle an average school or college quite sufficiently. In many cases, you can get away with a virtual environment such as a VPS.

</div><div id="section_3">

===Software===

* '''Linux''' - any distribution should be fine, Debian or Ubuntu are recommended as they're most regularly tested on, and even have debian packages.
* '''PHP''' - 5.3 or greater. You'll need [[System Administrator's Guide/Requirements#PHP|these PHP extensions]] also.
* '''PostgreSQL''' 8.3+, or '''MySQL''' 5.1+ with '''InnoDB''' table support.
* '''Apache''' - 2.0 or higher

[[System Administrator's Guide/Requirements#Software|More details about the Software Requirements]] are available, including what you can substitute for any of them.

==Get the code, and put on your webserver==

In order for your Mahara to run, you need to put a copy of the code on your own server. You can either [[Download Mahara|download a standard build of Mahara]], or [[Developer Area/Getting Code from Git|check out the project from the git repository]] if you know how git works (this option is mainly for developers).

Once you have the code, copy the contents of the <code>htdocs/</code> directory to your webserver. It is best if you either:

* Copy the entire directory, then rename it to something like 'mahara' - so you will see your site at <code>example.org/mahara/</code>; or
* Copy the contents of the <code>htdocs/</code> directory to the top level public directory (often called <code>htdocs</code> or <code>public_html</code>) of your webserver, so you can see your site at <code>example.org.</code>

If you are unfamiliar with Ubuntu and need an in more detailed explanation about how to install the files and configure Apache, go to the [[System Administrator's Guide/Installing Mahara/How to install Mahara in Ubuntu|step-by-step guide]].

</div><div id="section_5">

==Create the Database==

You need to create a database for Mahara and ensure that the webserver is able to connect to it. Instructions for the command line follow, if you have access to a CPanel or similar software you can create the database using it instead.

Your database must be UTF8 encoded. The commands below create a UTF8 encoded database, if you use CPanel etc., then you will have to make sure it creates you a UTF8 database.

'''Command line instructions for Postgres:'''

 <nowiki># Run these commands while su'd to the 'postgres' user
  # If you need to create a database user:
  createuser -SRDP (username)
  # Actual database creation
  createdb -O (username who will be connecting) -EUTF8 (databasename)</nowiki>

'''Command line instructions for MySQL:'''

 mysql --user=root -p
 
  [enter password]
 
  create database (databasename) character set UTF8;
 
  grant all on (databasename).* to 'username'@'localhost' identified by 'password';

By the way, if possible, [[System Administrator's Guide/PostgreSQL or MySQL%3f|try to use PostgreSQL for your database]] if you can.

</div><div id="section_6">

==Create the Dataroot Directory==

This is a directory where Mahara will write files that are uploaded to it, as well as some other files it needs to run. The main point about this directory is that it is one that the web server can write to. The other main point is that it cannot be inside the directory where your Mahara code is! In fact, if you have a public_html directory, it should not be inside that at all.

On your webserver, you will need to make this directory. If you have a public_html directory, make the directory alongside it. You can give it a name like 'maharadata'. Once you are done, you should have this directory structure (ignoring files):

 <code>.../yourusername/public_html</code>
  <code>.../yourusername/maharadata</code>

You will need to make the maharadata directory writable by the web server user. You can either change its owner to be the web server user, or you can <code>chmod</code> it to 777. The latter isn't recommended, but if you're on shared hosting it's what you'll probably have to do. FTP programs will allow you to chmod the directory.

</div><div id="section_7">

==Create Mahara's config.php==

In the Mahara htdocs directory is <code>config-dist.php</code>. You need to make a copy of this called <code>config.php</code>. You then need to go through the file and make changes where appropriate. The file is commented, and there are not many settings to change. However, take special note of the following settings:

* '''database connection details''' — ensure you include the database connection details by inserting the proper values for $cfg-&gt;dbname, $cfg-&gt;dbuser, $cfg-&gt;dbpass, $cfg-&gt;dbprefix.
** '''Note''': You do ''not'' need to set dbprefix, unlike Moodle. Try not using it first, and see if it works. If you find you ''do'' need it, you may find it best to leave dbprefix empty and add the prefix directly to $cfg-&gt;dbname, $cfg-&gt;dbuser values.
* '''dataroot''' - set this to the filesystem path to the directory you made that the web server user can write to. Please note this is a filesystem path, which on linux will look like <code>/path/to/your/directory</code> and on windows will look like <code>C:\path\to\your\directory</code>. This is NOT a web address such as http://example.org/maharadata!
* '''directorypermissions''' - if you're on a server where you do not have root access, you should change this from 0700 to 0777 or similar, so that you can download your dataroot later for backup purposes, and install language packs.

</div><div id="section_8">

==Apache Configuration==

''<span style="background-color: rgb(255, 204, 153)">'''Note:''' If you're on shared hosting, you probably are not able to change this, so you can ignore this section.</span>''

The simplest of Apache VirtualHost configurations will be sufficient:

 
          ServerName example.org
          DocumentRoot /path/to/mahara/htdocs
 
          ErrorLog /var/log/apache2/mahara.error.log
          CustomLog /var/log/apache2/mahara.access.log combined
 
 
                  AllowOverride All
 
 

Please note that your apache configuration should contain '''no ServerAliases'''. Mahara expects to be accessed through ONE URL. This gives certainty that cookies are set for the right domain, and also means that SSL certificates for the networking functionality can be generated for this one URL. If you use a server alias, you should expect to see problems like having to log in twice, and potentially SSO between your site and others breaking.

However, you can still make both example.org and www.example.org work for your site, if you use a second VirtualHost directive as well as the one above:

 
      ServerName www.example.org
      # You _can_ add ServerAliases here if you want more than one URL to
      # redirect to your main site
      # ServerAlias foo.example.org
 
      Redirect Permanent / http://example.org/
 

</div><div id="section_9">

==Adjust your PHP settings==

In your php.ini file (often found in /etc/php5/apache2/php.ini), make sure you have these:

 register_globals off
  magic_quotes_runtime off
  magic_quotes_sybase off
  magic_quotes_gpc off
  log_errors on
  allow_call_time_pass_reference off
  upload_max_filesize 50M
  post_max_size 50M

</div><div id="section_10">

==Run the Web Based Installer==

Once you have set up your config.php (and apache configuration, if not on shared hosting), you should now be able to navigate to the Mahara installation using your web browser. This will pop up a page stating the conditions of using Mahara, and will ask for agreement. If you agree with the conditions, click "agree" and Mahara will install itself into your database. Click continue, and you will be asked to change the administrator's password, then you'll be logged in to your new Mahara installation. '''Congratulations!'''

'''Note:''' The admin's username is ''''admin''''. Before Mahara 1.2, you will have to log in before you can change your password. The admin's default password is '''mahara'''.

<div id="section_11">

===What if the installation process breaks with an error?===

Sometimes this can happen. Normally this is because of some misconfiguration in your system - for example, you haven't granted your database user permission to create tables, or you aren't using a high enough version of your database (see the [[System Administrator's Guide/Installing Mahara#1.%20Dependencies|dependencies]]). Sometimes, it's because of a bug in the Mahara installer. In order to find out, you will need to check the error log for your webserver. Mahara dumps detailed information in there where a bug occurs.

The message might show you that the problem is with your configuration, but if it looks like a problem with Mahara, you should make a [http://mahara.org/tracker bug report] with the information from your logs, so we can fix it.

If you were able to fix the problem, you might need to drop and re-create your database again, so you're starting the installation again without any of the previously installed tables in the way.

</div><div id="section_12">

===Final Tasks (don't forget!): Email &amp; Cron Job===

1. You may wish to check that Mahara can send email by trying to register on your site. If you receive a registration email, all is well. If you get a message saying "Sorry, your registration attempt was unsuccessful. This is our fault, not yours...", then you will need to install a mail transport agent (such as sendmail, exim, postfix, nullmailer) on your server, or specify an outgoing (SMTP) mail server in your config.php (form version 1.4 mail settings can be configured in ''Configure Site -> Site options -> Email''). See the [[System Administrator's Guide/Installing Mahara/Troubleshooting|troubleshooting page]], or [http://mahara.org/interaction/forum/topic.php?id=985 this thread] for more details.

2. You will need to set up a cron job to hit <font face="Courier New">htdocs/lib/cron.php</font> every minute. Mahara implements its own cron internally, so hitting cron every minute is sufficient to make everything work.

If you don't set up the cron job, you will find that RSS feeds will not update, and some email notifications won't be sent out, such as forum post notifications.

You can set it up using the command line 'php' command to run the cron script, or by using a command line web browser such as lynx or w3m.

Something like the following in a crontab file will be sufficient:

 <nowiki>* * * * * curl http://your-mahara-site.org/lib/cron.php</nowiki>

If you run cron using curl, the cron output will be logged in your apache error log. If you wish to separate where it's logged to away from your apache logs (which is a particularly good idea, though slightly harder to set up), read the [[System Administrator's Guide/Cron Job|separate article about Mahara's cron]].

</div><div id="section_13">

===Secure your Mahara installation===

There are a few things that can be done to increase the security of your installation by enabling '''virus scanning''' and extra '''spam protections'''.

Have a look under Sites options, Security settings.

</div><div id="section_14">

===My Mahara is installed - now what?===

Congratulations on getting your Mahara installed! Now read the [[System Administrator's Guide/Next Steps|Next Steps article]] to see what you can do now - for example, installing a new language pack and theme.

And if you haven't already, now might be a good time to join the Mahara community - you can get help and ideas for your Mahara from a world-wide community of enthusiastic users. We hope to see you on the forums soon!

</div><div id="section_15">

===Troubleshooting===

If you are having problems installing Mahara, please check out the [[System Administrator's Guide/Installing Mahara/Troubleshooting|Installation Instructions Troubleshooting Page]] for answers to some common problems.

</div></div>

===Subpages===

* [[System_Administrator's_Guide/Installing_Mahara/How_to_install_Mahara_in_Ubuntu|How to install Mahara in Ubuntu]]
* [[System_Administrator's_Guide/Installing_Mahara/Installing_Mahara_in_Wampserver|Installing Mahara in Wampserver]]
* [[System_Administrator's_Guide/Installing_Mahara/Installing_on_CentOS_5.x|Installing on CentOS 5.x]]
* [[System_Administrator's_Guide/Installing_Mahara/MAC_Installation|Mahara on Mac OS X]]
* [[System_Administrator's_Guide/Installing_Mahara/Mahara_on_fastcgi//nginx|Mahara on fastcgi/nginx]]
* [[System_Administrator's_Guide/Installing_Mahara/Troubleshooting|Troubleshooting]]