Difference between revisions of "System Administrator's Guide/Installing Mahara/Installing Mahara in Wampserver"

From Mahara Wiki
Jump to navigation Jump to search
(Troubleshooting)
 
(4 intermediate revisions by 2 users not shown)
Line 11: Line 11:
 
'''3.''' Extract the contents of the Mahara zip file in a temporary directory. Rename the htdocs subdirectory to 'mahara' (without the quotes) and then move that subdirectory inside the /www directory that Wampserver has created in your hard-drive (we'll assume it's C:\wamp\www). Also create the data directory for Mahara inside the Wampserver installation directory (we'll assume it's C:\wamp\data).
 
'''3.''' Extract the contents of the Mahara zip file in a temporary directory. Rename the htdocs subdirectory to 'mahara' (without the quotes) and then move that subdirectory inside the /www directory that Wampserver has created in your hard-drive (we'll assume it's C:\wamp\www). Also create the data directory for Mahara inside the Wampserver installation directory (we'll assume it's C:\wamp\data).
  
'''4.''' The next step is to configure all the variables in the config-dist.php file. You need to complete this file with the values of your installation:
+
'''4.''' In your "mahara" directory (at C:\wamp\www\mahara) find the file named <code>config-dist.php</code>. This is the default configuration file. Make a copy of it named <code>config.php</code>. This will be your actual configuration file. Open <code>config.php</code> in a text editor and populate these values (you'll find they're already documented in the file itself):
  
<font size="smaller">$cfg-&gt;dbtype   = 'mysql5'; <br />$cfg-&gt;dbhost   = 'localhost';<br />$cfg-&gt;dbport  = null;<br />$cfg-&gt;dbname   = 'mahara';  // this is the name of the mahara database<br />$cfg-&gt;dbuser   = 'root'; // this is usually the default user for the database administrator.<br /><nowiki>$cfg-&gt;dbpass   = ''; If you have added a password to your root user, you should add the password here.</nowiki><br /><nowiki>$cfg-&gt;dbprefix = '';</nowiki></font>
+
<source lang="php">
 +
// Database connection details
 +
$cfg->dbtype = 'mysql';
 +
$cfg->dbhost = 'localhost';
 +
$cfg->dbname = 'mahara';  // this is the name of the mahara database
 +
$cfg->dbuser = 'root'; // this is usually the default user for the database administrator.
 +
$cfg->dbpass = ''; // If you have added a password to your root user, you should add the password here.
  
You need to configure the paths for the wwwroot and dataroot directories with the values in your installation. In my case: $cfg-&gt;wwwroot = '[http://localhost/mahara/ http://localhost/mahara/']; and $cfg-&gt;dataroot = 'C:\\wamp\\data'; (the double slashes '''are important''').
+
// The URL for Mahara in your WAMP server
 +
$cfg->wwwroot = 'http://localhost/mahara/';
  
Leave the rest of the config-dist file as it is. Once you have saved the file, rename it as “config.php”
+
// The "dataroot", a directory outside of the WAMP web content directory,
 +
// where Mahara can store uploaded user files. The WAMP Apache server
 +
// will need read/write access to this directory.
 +
$cfg->dataroot = 'C:\\wamp\\data'; // (the double slashes ARE IMPORTANT).
 +
</source>
 +
 
 +
Once you've filled in these fields, you can save and close your <code>config.php</code> file.
  
 
'''5.''' Before launching Mahara, we need to create the database, with the same name that we have set up in the config.php file. For that, go to the “phpmyAdmin” menu of “Wampserver”. Type “mahara” -or the name you have added for your database in the config file- in the box “create new database”, select “utf8_unicode_ci” in the drop down select box and click on the “Create” button.
 
'''5.''' Before launching Mahara, we need to create the database, with the same name that we have set up in the config.php file. For that, go to the “phpmyAdmin” menu of “Wampserver”. Type “mahara” -or the name you have added for your database in the config file- in the box “create new database”, select “utf8_unicode_ci” in the drop down select box and click on the “Create” button.
Line 23: Line 36:
 
'''6.''' Once the database has been created, go to the “localhost” option of Wampserver. You will see that under “Project” (it's called “Your Projects” under Wampserver 2.0h and above), there is a new folder called “mahara”. Click on it in order to complete the installation.
 
'''6.''' Once the database has been created, go to the “localhost” option of Wampserver. You will see that under “Project” (it's called “Your Projects” under Wampserver 2.0h and above), there is a new folder called “mahara”. Click on it in order to complete the installation.
  
If everything goes OK, Mahara will start installing the different pluggins and components in the database.
+
If everything goes OK, Mahara will start installing the different plugins and components in the database.
 
 
When the installation finishes, if everything goes OK, you will be prompted to log in first time in Mahara as administrator (remember that the username is “admin” and the password “mahara”).
 
  
<div id="section_1">
+
When the installation finishes, if everything goes OK, you will be logged in as the default "admin" user, and prompted to set a password.
  
 
=Troubleshooting=
 
=Troubleshooting=
Line 43: Line 54:
 
'''A:''' Are you using Wampserver 2.0h?...  Although we cannot guarantee that the following instructions are going to solve your problem, try this:
 
'''A:''' Are you using Wampserver 2.0h?...  Although we cannot guarantee that the following instructions are going to solve your problem, try this:
  
# In the php.ini, increase the values of the following variables:
+
1. In the php.ini, increase the values of the following variables:
 +
 
 +
max_execution_time = 120
 +
memory_limit = 256M.
 +
 
 +
(just restart all wampserver services after that)
 +
 
 +
2. If there is an incomplete Mahara database already created by the installer, just delete it and start the installation again, by going to the step 6 of the previous section.
 +
 
 +
As I mentioned before, we cannot guarantee that this is going to solve your problem. Mahara was developped to run on linux/unix distributions from the very beginning, and we are trying different "patches" to make it work with  windows.
 +
 
 +
If this does not solve your problem, you can ask for additional help at Mahara Community.
 +
 
 +
'''Q: Dates and times are off by an hour or more'''
  
max_execution_time = 120
+
'''A:''' You may have a discrepancy between your database's timezone, and PHP's timezone. See: https://wiki.mahara.org/wiki/System_Administrator's_Guide/Installing_Mahara/Troubleshooting#Q:_Time_zone_problems_.2F_Mahara_is_showing_incorrect_times_for_forum_posts
  
memory_limit = 256M.
+
'''Q: Some dates and times are blank'''
  
(just restart all wampserver services after that)
+
'''A:''' This is a specific known bug when running Mahara in Windows: https://bugs.launchpad.net/mahara/+bug/1451328
  
2. Open the file hdocts/lib/db/install.xml and replace the code for view_layout table with this one:
+
To test if you are experiencing this particular bug: log in as admin, go to the "Administration -> Users" screen, and look up the admin user you just logged in as. If the "Last Login" column is blank, you are probably experiencing this bug.
  
<font face="courier new,courier"><font size="1"></font></font>
+
The cause of this bug, is that the standard C strftime library for Windows doesn't support some of the date formats used by Mahara. You can work around this by using a [[Developer_Area/Language_strings#Custom_lang_strings_in_.2Flocal|local language string file]]. Create a new file at <code>C:\wamp\www\mahara\local\lang\en.utf8\langconfig.php</code> with these contents:
  
{|
+
<source lang="php">
|
+
<?php
<br />   <br />     <br />     <font size="1" color="#ff0000">1columns</font><font size="1">" TYPE="int" LENGTH="1" NOTNULL="true"/&gt;<br />     <br />   </font><br />   <br />     <br />     <font size="1" color="#ff0000">1columns</font><font size="1">,widths"/&gt;<br />   </font><br />
+
// Overriding datetime format strings to make them Windows-compatible
|}
+
defined('INTERNAL') || die();
  
where the original field "columns" have been now replaced by "<font color="rgb(255, 0, 0)">1columns</font>" (you will be able to rename again this field once the Mahara database has been created).
+
// replacing "l" (lowercase L) with "I" (uppercase i)
 +
$string['strftimedatetime'] = '%%d %%B %%Y, %%I:%%M %%p';
 +
$string['strftimedaydatetime'] = '%%A, %%d %%B %%Y, %%I:%%M %%p';
 +
$string['strftimerecentfull'] = '%%a, %%d %%b %%Y, %%I:%%M %%p';
 +
$string['strftimetime'] = '%%I:%%M %%p';
  
3. If there is an incomplete Mahara database already created by the installer, just delete it and start the installation again, by going to the step 6 of the previous section.
+
// replacing "e" with "d"
 +
$string['strftimedate'] = '%%d %%B %%Y';
  
As I mentioned before, we cannot guarantee that this is going to solve your problem. Mahara was developped to run on linux/unix distributions from the very beginning, and we are trying different "patches" to make it work with  windows.
+
// replacing "k" with "H"
 +
$string['strftimedaytime'] = '%%a, %%H:%%M';
 +
$string['strftimerecent'] = '%%d %%b, %%H:%%M';
  
If this does not solve your problem, you can ask for additional help at Mahara Community.
+
// deleting "z"
 +
$string['strftimew3cdatetime'] = '%%Y-%%m-%%dT%%H:%%M:%%S';
 +
</source>
  
</div>
+
If you are using additional languages besides English, you may need to make a separate file for each of them in their own directory. You can use the list of non-supported formats here to help find problem strings and how to fix them: https://bugs.launchpad.net/mahara/+bug/1451328/comments/7

Latest revision as of 15:28, 25 August 2016

If you need to set up a Mahara development site, and you don´t have prior knowledge of Debian-Ubuntu, you can install Mahara under WAMPSERVER. This last one is a web development environment which allows to run web applications using Apache, MySQL and php in a windows environment. It also includes phpmyAdmin and SQLiteManager to manage the databases.

The following steps have been only tested with Wampserver 2.0c, so if you have already a previous version installed and doesn’t work, you may need to upgrade to 2.0c.

If you are using a newer version, such as Wampserver 2.0h, you may find useful the troubleshooting section, at the end of this page.

1. The first step is to download and install the latest version of WAMPSERVER. This installation is pretty straightforward and you shouldn’t have any problems with it. Once it is installed, click on the shortcut Wampserver icon displayed on screen. You will notice a new small icon display on the bottom left of the taskbar. You can activate the different utilities of WAMPSERVER by clicking on that small icon.

2. Download the latest stable version of Mahara (we'll assume you've downloaded the .zip file).

3. Extract the contents of the Mahara zip file in a temporary directory. Rename the htdocs subdirectory to 'mahara' (without the quotes) and then move that subdirectory inside the /www directory that Wampserver has created in your hard-drive (we'll assume it's C:\wamp\www). Also create the data directory for Mahara inside the Wampserver installation directory (we'll assume it's C:\wamp\data).

4. In your "mahara" directory (at C:\wamp\www\mahara) find the file named config-dist.php. This is the default configuration file. Make a copy of it named config.php. This will be your actual configuration file. Open config.php in a text editor and populate these values (you'll find they're already documented in the file itself):

// Database connection details
$cfg->dbtype = 'mysql';
$cfg->dbhost = 'localhost';
$cfg->dbname = 'mahara';  // this is the name of the mahara database
$cfg->dbuser = 'root'; // this is usually the default user for the database administrator.
$cfg->dbpass = ''; // If you have added a password to your root user, you should add the password here.

// The URL for Mahara in your WAMP server
$cfg->wwwroot = 'http://localhost/mahara/';

// The "dataroot", a directory outside of the WAMP web content directory,
// where Mahara can store uploaded user files. The WAMP Apache server
// will need read/write access to this directory.
$cfg->dataroot = 'C:\\wamp\\data'; // (the double slashes ARE IMPORTANT).

Once you've filled in these fields, you can save and close your config.php file.

5. Before launching Mahara, we need to create the database, with the same name that we have set up in the config.php file. For that, go to the “phpmyAdmin” menu of “Wampserver”. Type “mahara” -or the name you have added for your database in the config file- in the box “create new database”, select “utf8_unicode_ci” in the drop down select box and click on the “Create” button.

6. Once the database has been created, go to the “localhost” option of Wampserver. You will see that under “Project” (it's called “Your Projects” under Wampserver 2.0h and above), there is a new folder called “mahara”. Click on it in order to complete the installation.

If everything goes OK, Mahara will start installing the different plugins and components in the database.

When the installation finishes, if everything goes OK, you will be logged in as the default "admin" user, and prompted to set a password.

Troubleshooting

Q: I got an error message saying that "the curl extension is not included". How can I enable it? 

A: You can enable additional extensions in the file php.ini. The easiest way to do so is by clicking on the Wampserver icon, going to the php folder visible icon and clicking on the the php.ini file. Then, you need to uncomment the line "extension=php_curl line" and save the file. Next click on the Wampserver icon and select “Restart all services”. Then go back to your browser window and click on the “refresh” button to restart the Mahara installation.

Q: I got an error message saying that "Your server does not have the mime_magic extension enabled. Mahara may have trouble detecting file types". How can I fix this? 

A: You need to use the Fileinfo extension (as the original Mime Magic extension has been deprecated).

Q: I have followed all the aforementioned steps, but Mahara gets stuck when installing the first component (core code).

A: Are you using Wampserver 2.0h?...  Although we cannot guarantee that the following instructions are going to solve your problem, try this:

1. In the php.ini, increase the values of the following variables:

max_execution_time = 120
memory_limit = 256M.

(just restart all wampserver services after that)

2. If there is an incomplete Mahara database already created by the installer, just delete it and start the installation again, by going to the step 6 of the previous section.

As I mentioned before, we cannot guarantee that this is going to solve your problem. Mahara was developped to run on linux/unix distributions from the very beginning, and we are trying different "patches" to make it work with  windows.

If this does not solve your problem, you can ask for additional help at Mahara Community.

Q: Dates and times are off by an hour or more

A: You may have a discrepancy between your database's timezone, and PHP's timezone. See: https://wiki.mahara.org/wiki/System_Administrator's_Guide/Installing_Mahara/Troubleshooting#Q:_Time_zone_problems_.2F_Mahara_is_showing_incorrect_times_for_forum_posts

Q: Some dates and times are blank

A: This is a specific known bug when running Mahara in Windows: https://bugs.launchpad.net/mahara/+bug/1451328

To test if you are experiencing this particular bug: log in as admin, go to the "Administration -> Users" screen, and look up the admin user you just logged in as. If the "Last Login" column is blank, you are probably experiencing this bug.

The cause of this bug, is that the standard C strftime library for Windows doesn't support some of the date formats used by Mahara. You can work around this by using a local language string file. Create a new file at C:\wamp\www\mahara\local\lang\en.utf8\langconfig.php with these contents:

<?php
// Overriding datetime format strings to make them Windows-compatible
defined('INTERNAL') || die();

// replacing "l" (lowercase L) with "I" (uppercase i)
$string['strftimedatetime'] = '%%d %%B %%Y, %%I:%%M %%p';
$string['strftimedaydatetime'] = '%%A, %%d %%B %%Y, %%I:%%M %%p';
$string['strftimerecentfull'] = '%%a, %%d %%b %%Y, %%I:%%M %%p';
$string['strftimetime'] = '%%I:%%M %%p';

// replacing "e" with "d"
$string['strftimedate'] = '%%d %%B %%Y';

// replacing "k" with "H"
$string['strftimedaytime'] = '%%a, %%H:%%M';
$string['strftimerecent'] = '%%d %%b, %%H:%%M';

// deleting "z"
$string['strftimew3cdatetime'] = '%%Y-%%m-%%dT%%H:%%M:%%S';

If you are using additional languages besides English, you may need to make a separate file for each of them in their own directory. You can use the list of non-supported formats here to help find problem strings and how to fix them: https://bugs.launchpad.net/mahara/+bug/1451328/comments/7