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,

• http://mahara.example.com/user/bob
• http://mahara.example.com/user/bob/bobs-portfolio-page
• http://mahara.example.com/group/bobs-group
• http://mahara.example.com/group/bobs-group/an-interesting-group-page

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

• http://mahara.example.com/user/view.php?id=123
• http://mahara.example.com/group/view.php?id=456
• http://mahara.example.com/view/view.php?id=789

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

• http://mahara.example.com/user/view.php?profile=bob

Group homepages are also accessible at

• http://mahara.example.com/group/view.php?homepage=bobs-group

Portfolio pages owned by users and groups are accessible at

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

Your webserver needs to convert urls such as http://mahara.example.com/user/bob to http://mahara.example.com/user/view.php?profile=bob, 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 set one up during installation. Add the following lines before the closing </VirtualHost> tag:

 <IfModule mod_rewrite.c>
   RewriteEngine on
   RewriteRule ^<path of wwwroot>/user/([a-z0-9-]+)/?$ <path of wwwroot>/user/view.php?profile=$1&%{QUERY_STRING}
   RewriteRule ^<path of wwwroot>/user/([a-z0-9-]+)/([a-z0-9-]+)/?$ <path of wwwroot>/view/view.php?profile=$1&page=$2&%{QUERY_STRING}
   RewriteRule ^<path of wwwroot>/group/([a-z0-9-]+)/?$ <path of wwwroot>/group/view.php?homepage=$1&%{QUERY_STRING}
   RewriteRule ^<path of wwwroot>/group/([a-z0-9-]+)/([a-z0-9-]+)/?$ <path of wwwroot>/view/view.php?homepage=$1&page=$2&%{QUERY_STRING}
 </IfModule>

Note: <path of wwwroot> is the path of your $cfg->wwwroot defined in the config.php

• 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-]+)/?$ <path of wwwroot>/user/view.php?profile=$1&%{QUERY_STRING}
   RewriteRule ^user/([a-z0-9-]+)/([a-z0-9-]+)/?$ <path of wwwroot>/view/view.php?profile=$1&page=$2&%{QUERY_STRING}
   RewriteRule ^group/([a-z0-9-]+)/?$ <path of wwwroot>/group/view.php?homepage=$1&%{QUERY_STRING}
   RewriteRule ^group/([a-z0-9-]+)/([a-z0-9-]+)/?$ <path of wwwroot>/view/view.php?homepage=$1&page=$2&%{QUERY_STRING}
 </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"

Instructions for Nginx

• Add the following rewrite rules to the server { } block

   rewrite ^/user/([a-z0-9-]+)/?$ /user/view.php?profile=$1&$query_string;
   rewrite ^/user/([a-z0-9-]+)/([a-z0-9-]+)/?$ /view/view.php?profile=$1&page=$2&$query_string;
   rewrite ^/group/([a-z0-9-]+)/?$ /group/view.php?homepage=$1&$query_string;
   rewrite ^/group/([a-z0-9-]+)/([a-z0-9-]+)/?$ /view/view.php?homepage=$1&page=$2&$query_string;

• Restart nginx

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.

• http://mahara.example.com/user/bob/bobs-portfolio-page
• http://mahara.example.com/user/bob/bobs-portfolio-page-1, 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 http://mahara.example.com/profile/bob, 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.

Note: 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 http://mahara.example.com/user/view.php will be matched by your rewrite rule and converted to http://mahara.example.com/user/view.php?profile=view.php, which is probably not what you want.

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

User subdomain option

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

Warning: 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.

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 general rewrite rules above, but still inside the <IfModule mod_rewrite.c> 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 http://admin.mahara.example.com in the location bar.