Difference between revisions of "System Administrator's Guide/Clean URL Configuration"
From Mahara Wiki
(Created page with "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/…")
Revision as of 15:32, 14 May 2012
From Mahara 1.6, you can configure your site to use human-readable URLs for user profiles, group homepages and portfolio pages. For example,
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
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
Group homepages are also accessible at
Portfolio pages owned by users and groups are accessible at
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")
- Add the following rules into the VirtualHost file for your site:
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
- 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.
- 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.
If you change any of these 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.