View source for System Administrator's Guide/Clean URL Configuration

From Mahara 1.6, you can configure your site to use human-readable URLs for user profiles, group homepages and portfolio pages. For example,

* <nowiki>http://mahara.example.com/user/bob</nowiki>
* <nowiki>http://mahara.example.com/user/bob/bobs-portfolio-page</nowiki>
* <nowiki>http://mahara.example.com/group/bobs-group</nowiki>
* <nowiki>http://mahara.example.com/group/bobs-group/an-interesting-group-page</nowiki>

The strings identifying the user, group and page are all editable within Mahara.

There are two steps to this - you must configure your webserver to rewrite URLs of incoming requests.  Once you've done that, you can then configure your Mahara site to generate clean URLs internally, and let your users pick their URLs.

= Configure your webserver =

By default, profile pages, group homepages, and portfolio pages are accessible at URLs like

* <nowiki>http://mahara.example.com/user/view.php?id=123</nowiki>
* <nowiki>http://mahara.example.com/group/view.php?id=456</nowiki>
* <nowiki>http://mahara.example.com/view/view.php?id=789</nowiki>

In Mahara 1.6, users, groups and portfolio pages also have a readable "url id" which is chosen by the user.  Profile pages are also accessible at

* <nowiki>http://mahara.example.com/user/view.php?profile=bob</nowiki>

Group homepages are also accessible at

* <nowiki>http://mahara.example.com/group/view.php?homepage=bobs-group</nowiki>

Portfolio pages owned by users and groups are accessible at

* <nowiki>http://mahara.example.com/view/view.php?profile=bob&page=bobs-portfolio-page</nowiki>
* <nowiki>http://mahara.example.com/view/view.php?homepage=bobs-group&page=an-interesting-group-page</nowiki>

Your webserver needs to convert urls such as <nowiki>http://mahara.example.com/user/bob</nowiki> to <nowiki>http://mahara.example.com/user/view.php?profile=bob</nowiki>, etc.

=== Instructions for Apache2 ===

* Enable the rewrite module (in Debian/Ubuntu: "a2enmod rewrite")
* Edit the '''Apache configuration file''' for your site.  You may need to create this file, or you may have already [[System_Administrator%27s_Guide/Installing_Mahara#Apache_Configuration|set one up during installation]].  Add the following lines before the closing </VirtualHost> tag:
  <IfModule mod_rewrite.c>
    RewriteEngine on
    RewriteRule ^/user/([a-z0-9-]+)/?$ /user/view.php?profile=$1
    RewriteRule ^/user/([a-z0-9-]+)/([a-z0-9-]+)/?$ /view/view.php?profile=$1&page=$2
    RewriteRule ^/group/([a-z0-9-]+)/?$ /group/view.php?homepage=$1
    RewriteRule ^/group/([a-z0-9-]+)/([a-z0-9-]+)/?$ /view/view.php?homepage=$1&page=$2
  </IfModule>
* Alternatively, if you are on commercial hosting and do not have access to this file, your host might also allow apache directives to be specified in an '''htaccess file''', so try adding the following lines above into a file named '.htaccess' in your web root folder:
  <IfModule mod_rewrite.c>
    RewriteEngine on
    RewriteRule ^user/([a-z0-9-]+)/?$ /user/view.php?profile=$1
    RewriteRule ^user/([a-z0-9-]+)/([a-z0-9-]+)/?$ /view/view.php?profile=$1&page=$2
    RewriteRule ^group/([a-z0-9-]+)/?$ /group/view.php?homepage=$1
    RewriteRule ^group/([a-z0-9-]+)/([a-z0-9-]+)/?$ /view/view.php?homepage=$1&page=$2
  </IfModule>
* Restart apache
* Verify that the rewrite is working.  Browse to a URL on your site such as <wwwroot>user/admin
** If the rewrite is working correctly, you will see an error message with your Mahara site header saying "The page you are looking for could not be found ... User admin not found"
** If the rewrite is '''not''' working correctly, you will most likely see a generic error from your webserver, with a message like "The requested URL /user/admin was not found on this server"

= Enable the Clean URLs option in Mahara =

In the config.php file for your Mahara site, add the following line:

 $cfg->cleanurls = true;

Once this is enabled, any new users, groups and pages will have clean URLs generated automatically, but they can also be edited on the site.

* User URL fragments are 3-30 characters long, and can be edited on the Settings page (account/index.php)
* Group URL fragments are 3-30 characters long, and are edited on the edit group page (group/edit.php)
* Portfolio page URL fragments owned by users and groups are 3-100 characters, and can be edited under "Edit title & description" in the page editor (view/edit.php)

All these fields may contain only lowercase letters from a-z, digits, and hyphens.

= Upgrade all users, groups and pages to use Clean URLs (optional) =

In the admin area, under Site Administration -> Extensions -> Clean URLs, there is a button that will regenerate all clean URLs.  This is useful when you want to initialise URLs throughout your site.

* User URLs will be generated based on usernames
* Group URLs are based on the group name
* Portfolio page URLs are based on the page title

Duplicates are avoided by appending a hyphen followed by digits, e.g.
* <nowiki>http://mahara.example.com/user/bob/bobs-portfolio-page</nowiki>
* <nowiki>http://mahara.example.com/user/bob/bobs-portfolio-page-1</nowiki>, etc.

If you enable clean URLs, but you don't perform this step, the site will still work fine.  Existing pages will still be accessed using ids.

= Advanced Configuration (experimental and slightly dangerous) =

* You may change the default '''user''' and '''group''' strings given in the above examples with the additional $cfg->cleanurluserdefault and $cfg->cleanurlgroupdefault settings in config.php.  For example, if you want to change 'user' to 'profile', so that the clean URLs are of the form <nowiki>http://mahara.example.com/profile/bob</nowiki>, you would add "$cfg->cleanurluserdefault = 'profile';" in config.php, and change the first two rewrite rules above to use 'profile' in place of 'user'.

* You can also change the list of allowed characters by editing regular expressions in your config.php file.  See the file htdocs/lib/config-defaults.php of your Mahara installation for more information.

<div style="border: 1px dotted #ff8888; margin: 10px 0; padding: 10px; background-color: #f8f8f8;"><span style="color: red;">'''Note:'''</span> If you change either of the above options, you '''must''' make sure that your rewrite rules are changed appropriately, and also take care to ensure that your rewrite rules will never match any of Mahara's pages -- this may make them inaccessible.  For example, if you want allow the character '.' in your user urls, and you leave the cleanurluserdefault string as 'user', a URL such as <nowiki>http://mahara.example.com/user/view.php</nowiki> will be matched by your rewrite rule and converted to <nowiki>http://mahara.example.com/user/view.php?profile=view.php</nowiki>, which is probably not what you want.</div>

* If you wish to stop your users from editing their own urls, set $cfg->cleanurlusereditable = false; in config.php.

= User subdomain option (in progress, but likely to be available in 1.6) =

This option generates subdomain-style profile urls like <nowiki>http://bob.mahara.example.com</nowiki>

<div style="border: 1px dotted #ff8888; margin: 10px 0; padding: 10px; background-color: #f8f8f8;">'''<span style="color: red;">Warning:</span>''' Enabling this option on your site is likely to cause users with open sessions to be logged out on all profile pages.  To avoid this, expire all sessions by closing the site in the admin area and reopening it, '''before''' enabling this option.</div>

== Webserver configuration ==

=== Subdomain rewrite rules for Apache 2 ===

* In your VirtualHost configuration, find the ServerName directive, add a wildcard ServerAlias line after it.  If your ServerName is mahara.example.com, add

 ServerAlias *.mahara.example.com

* Add the following additional rewrite rules, '''after''' the [[System_Administrator%27s_Guide/Clean_URL_Configuration#Instructions_for_Apache2|general rewrite rules]] above, but still inside the <nowiki><IfModule mod_rewrite.c></nowiki> block

 RewriteCond %{HTTP_HOST} ^([a-z0-9-]+)\.example\.mahara\.com$
 RewriteRule ^/([a-z0-9-]+)/?$ /view/view.php?profile=%1&page=$1 [QSA]
 
 RewriteCond %{HTTP_HOST} ^([a-z0-9-]+)\.example\.mahara\.com$
 RewriteRule ^/?$ /user/view.php?profile=%1 [QSA]

* Replace '''\.example\.mahara\.com''' in the above rules with your wwwroot.

* Restart apache

== Enable the user subdomain option in config.php ==

 $cfg->cleanurlusersubdomains = true;

Now test it:

* Clear your site's cookies from your browser
* Log in
* Check that you have set your profile url on the settings page
* Click on your name in the top right.  You should be taken to your profile page, and the browser should be showing a subdomain url like <nowiki>http://admin.mahara.example.com</nowiki> in the location bar.