Wiki source code of Short XWiki URLs
Version 37.1 by Vincent Massol on 2013/09/19
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} | ||
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
| 5 | This tutorial shows you how to tune your XWiki platform by replacing the default URL scheme with a shorter scheme. | ||
| 6 | |||
| 7 | {{info}} | ||
| 8 | A short URL is an URL without the ##xwiki/bin/view## parts. | ||
| 9 | {{/info}} | ||
| 10 | |||
| 11 | = I. Application name = | ||
| 12 | |||
| 13 | The ##/xwiki/## part of the URL is the application name. It identifies the application that should process the request, and it allows a container to host more than one application. To change it you must refer to your container's documentation and find how to map the context path of a web application. For example on Tomcat it's enough to simply deploy the XWiki webapp in the ##webapps## directory, in a sub directory named after the application name you wish to use (e.g. ##webapps/myappname##). | ||
| 14 | |||
| 15 | A special case is when deploying XWiki as the ROOT application, which actually allows the application name part to be empty, so an URL can take the form ##server.com/bin/view/Space/Document##. Achieving this depends on the container, as there's no standard regarding the ROOT application. For example: | ||
| 16 | * in Tomcat, with the default configuration, all it takes is to deploy the XWiki web application in ##webapps##, in a sub directory named ##ROOT## (i.e. ##webapps/ROOT##). | ||
| 17 | * In Jetty, with the default configuration, all it takes is to deploy the XWiki web application in ##webapps##, in a sub directory named ##root##. Note that if you're using the Standalone distribution (which packages Jetty and HSQLDB) then you'll also need to: | ||
| 18 | ** Remove the existing ##webapps/root## directory which contains a redirect Servlet that automatically redirects root URLs to the ##xwiki## context. You won't need that anymore. | ||
| 19 | ** Rename the existing ##webapps/xwiki## directory into ##webapps/root##. | ||
| 20 | ** Remove the ##jetty/contexts/xwiki.xml## file and thus keep only the ##jetty/contexts/root.xml## file. Otherwise you'll get a warning in the console. | ||
| 21 | |||
| 22 | Refer to your container's documentation for more details. | ||
| 23 | |||
| 24 | = II. Servlet mapping name = | ||
| 25 | |||
| 26 | The second part is the hardest part to remove. It identifies the servlet that should process the page, which, for ##/bin/##, is the Struts servlet. Generically speaking, to get rid of ##/bin/##, you need to configure your system so that URLs matching ##/*## are mapped to the Struts Servlet (by default only ##/bin/*## URLs are mapped to the Struts Servlet). | ||
| 27 | |||
| 28 | However you need to be careful that the following prefixes do NOT go through the Struts Servlet (see your ##web.xml## to check their current mappings): | ||
| 29 | * ##/resources/*## and ##/skins/*##: Statically served resources. These need to be served directly as static resources. | ||
| 30 | * ##/rest/*##: REST resources, served by the XWiki REST Servlet | ||
| 31 | * ##/xmlrpc/*##: XML-RPC resources, served by the XWiki XMLRPC Servlet | ||
| 32 | * ##/resources/*~*/*.gwtrpc##: GWT-RPC calls, served by the XWiki GWT Servlet | ||
| 33 | * ##/webdav/*##: WebDav calls, served by the XWiki WebDAV Servlet | ||
| 34 | * ##/XWikiService##: Another XWiki GWT Servlet | ||
| 35 | * ##/redirect##: The XWiki Redirect Servlet used to redirect to the home page when no page is specified in the URL | ||
| 36 | |||
| 37 | There are various alternate ways to achieve this as detailed below. | ||
| 38 | |||
| 39 | {{info}} | ||
| 40 | You might be tempted to configure just your XWiki's ##web.xml## file [[but this won't work>>ShortURLsInvalid]]. | ||
| 41 | {{/info}} | ||
| 42 | |||
| 43 | XWiki also generates URL and you can tell it to generate URLs without the ##bin/## part by adding this piece of code in ##xwiki.cfg##: {{code language="none"}}xwiki.defaultservletpath={{/code}} (Note that this is not required with the UrlRewriteFilter solution described below since it rewrites outbound URLs too). | ||
| 44 | |||
| 45 | == UrlRewriteFilter == | ||
| 46 | |||
| 47 | {{info}}This is the simplest solution of all but you'll need XWiki 5.2+ because of [[this issue that was fixed in XWiki 5.2>>http://jira.xwiki.org/browse/XWIKI-9430]].{{/info}} | ||
| 48 | |||
| 49 | "UrlRewriteFilter" is a [[framework offering a Servlet Filter>>http://www.tuckey.org/urlrewrite/]] allowing to rewrite URLs. | ||
| 50 | |||
| 51 | Install steps: | ||
| 52 | 1. [[Download the JAR>>http://www.tuckey.org/urlrewrite/]] and put it in ##WEB-INF/lib## | ||
| 53 | 1. Edit your ##WEB-INF/web.xml## and add the ##<filter>## and ##filter-mapping## definitions [[as documented>>http://www.tuckey.org/urlrewrite/]] | ||
| 54 | 1. Drop the following content in a file at ##WEB-INF/urlrewrite.xml##:((( | ||
| 55 | {{code language="xml"}} | ||
| 56 | <?xml version="1.0" encoding="utf-8"?> | ||
| 57 | <!DOCTYPE urlrewrite PUBLIC "-//tuckey.org//DTD UrlRewrite 4.0//EN" | ||
| 58 | "http://www.tuckey.org/res/dtds/urlrewrite4.0.dtd"> | ||
| 59 | <urlrewrite> | ||
| 60 | |||
| 61 | <rule> | ||
| 62 | <note> | ||
| 63 | Ensure that URLs ending with .gwtrpc are not modified. | ||
| 64 | </note> | ||
| 65 | <from>^/(.*)\.gwtrpc$</from> | ||
| 66 | <to type="forward" last="true">-</to> | ||
| 67 | </rule> | ||
| 68 | |||
| 69 | <rule> | ||
| 70 | <note> | ||
| 71 | En sure that URLs that must not be served by the Struts Servlet are not modified. | ||
| 72 | </note> | ||
| 73 | <from>^/(bin|resources|skins|rest|webdav|xmlrpc)/(.*)$</from> | ||
| 74 | <to type="forward" last="true">-</to> | ||
| 75 | </rule> | ||
| 76 | |||
| 77 | <rule> | ||
| 78 | <note> | ||
| 79 | For all other URLs we prepend the "/bin/" prefix so that they get routed to the XWiki Action Servlet. | ||
| 80 | </note> | ||
| 81 | <from>^/(.*)$</from> | ||
| 82 | <to type="forward">/bin/$1</to> | ||
| 83 | </rule> | ||
| 84 | |||
| 85 | <outbound-rule> | ||
| 86 | <note> | ||
| 87 | Rewrite outbound URLs to remove the "/bin" part. | ||
| 88 | </note> | ||
| 89 | <from>/bin/(.*)/(.*)$</from> | ||
| 90 | <to>/$1/$2</to> | ||
| 91 | </outbound-rule> | ||
| 92 | |||
| 93 | </urlrewrite> | ||
| 94 | {{/code}} | ||
| 95 | ))) | ||
| 96 | |||
| 97 | == web.xml + Apache == | ||
| 98 | |||
| 99 | Do as above but instead of mapping the Default Servlet, bypass the Servlet container at the web front-end level. For example, if you are using Apache httpd as a front-end, and assuming a webapp deployed as a ROOT webapp and an AJP connection between httpd and the servlet container, the following configuration allows you to serve skin files and static resources directly from httpd: | ||
| 100 | |||
| 101 | {{code}} | ||
| 102 | Alias /skins /usr/local/xwiki/skins | ||
| 103 | Alias /resources /usr/local/xwiki/resources | ||
| 104 | ProxyPass /skins/ ! | ||
| 105 | ProxyPass /resources/ ! | ||
| 106 | {{/code}} | ||
| 107 | |||
| 108 | Note that this solution will not work for the WYSIWYG editor since it needs that the ##.gwtrpc## URLs are directed to the XWiki Servlet. The following Apache configuration using URL rewriting achieves this: | ||
| 109 | |||
| 110 | {{code}} | ||
| 111 | Alias /skins /usr/local/xwiki/skins | ||
| 112 | Alias /resources /usr/local/xwiki/resources | ||
| 113 | |||
| 114 | RewriteEngine on | ||
| 115 | |||
| 116 | RewriteRule ^/+skins - [L] | ||
| 117 | RewriteCond %{REQUEST_URI} !\.gwtrpc$ | ||
| 118 | RewriteRule ^/+resources($|/.*) - [L] | ||
| 119 | |||
| 120 | RewriteRule .* http://localhost:8080%{REQUEST_URI} [P,L] | ||
| 121 | ProxyPassReverse / http://localhost:8080/ | ||
| 122 | {{/code}} | ||
| 123 | |||
| 124 | {{warning}}Note that while this has been tested to work with XWiki 3.1, it seems it [[doesn't work with 4.5.4 and later>>http://jira.xwiki.org/browse/XWIKI-9455]].{{/warning}} | ||
| 125 | |||
| 126 | == Lighttpd + Jetty == | ||
| 127 | |||
| 128 | I used lighttpd, but I assume it can be done with other webservers too. This is the configuration I used in the lighttpd config (note that my xwiki folder has been moved to ##/usr/share/jetty/webapps/root## (no 'xwiki' at all)): | ||
| 129 | |||
| 130 | {{code language="none"}} | ||
| 131 | $HTTP["host"] =~ "^www\.domain\.com$" { | ||
| 132 | # ensure all requests for .gwtrpc files go through to java server | ||
| 133 | # we can put this rule first as a higher priority, which java couldn't do | ||
| 134 | $HTTP["url"] =~ "\.gwtrpc$" { | ||
| 135 | proxy.server = ( "" => (( "host" => "127.0.0.1", "port" => 8080 ))) | ||
| 136 | } | ||
| 137 | # otherwise, we can handle the static resources | ||
| 138 | else $HTTP["url"] =~ "^/resources/" { | ||
| 139 | alias.url += ( "/resources" => "/usr/share/jetty/webapps/root/resources" ) | ||
| 140 | } | ||
| 141 | # otherwise, we can handle the static resources | ||
| 142 | else $HTTP["url"] =~ "^/skins/" { | ||
| 143 | alias.url += ( "/skins" => "/usr/share/jetty/webapps/root/skins" ) | ||
| 144 | } | ||
| 145 | # and here is the primary server | ||
| 146 | else $HTTP["host"] =~ "^www\.domain\.com$" { | ||
| 147 | proxy.server = ( "" => (( "host" => "127.0.0.1", "port" => 8080 ))) | ||
| 148 | } | ||
| 149 | } | ||
| 150 | # redirect anything.domain.com to www.domain.com | ||
| 151 | else $HTTP["host"] =~ "\.domain\.com$" { | ||
| 152 | url.redirect = ( "^/(.*)" => "http://www.domain.com/$1" ) | ||
| 153 | server.name = "www.domain.com" | ||
| 154 | } | ||
| 155 | # redirect domain.com to www.domain.com | ||
| 156 | else $HTTP["host"] =~ "domain\.com$" { | ||
| 157 | url.redirect = ( "^/(.*)" => "http://www.domain.com/$1" ) | ||
| 158 | server.name = "www.domain.com" | ||
| 159 | } | ||
| 160 | {{/code}} | ||
| 161 | |||
| 162 | So lighttpd will serve any static content unless it has ##.gwtrpc## on the end of the URL. | ||
| 163 | |||
| 164 | If you use Nginx as a web-server, just add three more locations and set ##root## to them. By ##try_files## Nginx checks static content presence and if doesn't exist, redirect it to the Tomcat (we expect dynamic content in this case, including all ##*.gwtrpc## requests). | ||
| 165 | |||
| 166 | {{code}} | ||
| 167 | location /skins/ { | ||
| 168 | root /var/lib/tomcat7/webapps/ROOT; | ||
| 169 | } | ||
| 170 | |||
| 171 | location /resources/ { | ||
| 172 | try_files $uri $uri/ @fallback; | ||
| 173 | root /var/lib/tomcat7/webapps/ROOT; | ||
| 174 | } | ||
| 175 | |||
| 176 | location @fallback { | ||
| 177 | proxy_pass http://localhost:8080; | ||
| 178 | } | ||
| 179 | {{/code}} | ||
| 180 | |||
| 181 | In the example above XWiki installed as ROOT application in Tomcat. Change path to your XWiki application accordingly. | ||
| 182 | |||
| 183 | Then in ##web.xml##, I changed the ##gwtrpc## mapping to: | ||
| 184 | |||
| 185 | {{code language="xml"}} | ||
| 186 | <servlet-mapping> | ||
| 187 | <servlet-name>gwtrpc</servlet-name> | ||
| 188 | <url-pattern>/resources/*</url-pattern> | ||
| 189 | <url-pattern>/skins/*</url-pattern> | ||
| 190 | </servlet-mapping> | ||
| 191 | {{/code}} | ||
| 192 | |||
| 193 | Since we are using a url-pattern of ##/path/##, it will be specific enough to be a higher priority than the ##/## pattern we'll use next. And since the only thing that will come through via resources or skins will be ##gwtrpc##, then we can be sure it's ok. Note that only ##resources## is required, but I did both anyway. | ||
| 194 | |||
| 195 | Now, as described above, add a rule to catch everything else and redirect it to your XWiki servlet: | ||
| 196 | |||
| 197 | {{code language="xml"}} | ||
| 198 | <servlet-mapping> | ||
| 199 | <servlet-name>action</servlet-name> | ||
| 200 | <url-pattern>/*</url-pattern> | ||
| 201 | </servlet-mapping> | ||
| 202 | {{/code}} | ||
| 203 | |||
| 204 | = III. Struts action name = | ||
| 205 | |||
| 206 | The third part, ##/view/##, identifies the struts action that should process a request. So this tells what we want to do with the document, ##/view/## it, ##/edit/## it or ##/delete/## it, for example. The XWiki platform allows this part to be missing, considering that the default action is to just display the document, so an URL like ##server.com/bin/Space/Document## will work out of the box. | ||
| 207 | |||
| 208 | Even more, the URL factory, the component that generates URLs, can be configured to skip this part when the action is ##/view/##. To do this write this code in ##xwiki.cfg##: {{code language="none"}}xwiki.showviewaction=0{{/code}}. | ||
| 209 | |||
| 210 | = IV. Error Page = | ||
| 211 | |||
| 212 | At the ##WEB-INF/web.xml##, the ##location## of the 404 error code needs to be changed accordingly. For example: | ||
| 213 | |||
| 214 | {{code language="xml"}} | ||
| 215 | <error-page> | ||
| 216 | <error-code>404</error-code> | ||
| 217 | <!--<location>/xwiki/bin/view/Main/DocumentDoesNotExist</location>--> | ||
| 218 | <location>/bin/Main/DocumentDoesNotExist</location> | ||
| 219 | </error-page> | ||
| 220 | {{/code}} | ||
| 221 | |||
| 222 | = V. Conclusion = | ||
| 223 | |||
| 224 | After performing all these changes, you should be able to access documents with URLs like: | ||
| 225 | |||
| 226 | * server.com/Space/Document | ||
| 227 | * server.com/Space/ (pointing to Space.WebHome) | ||
| 228 | * server.com/Document (pointing to Main.Document) | ||
| 229 | * server.com/ will show Main.WebHome, without any redirect. | ||
| 230 | |||
| 231 | As a bonus, these changes are backwards compatible, meaning that any currently working URL will also work with these changes performed, so you won't have any broken bookmarks. |
