Hide last authors
Manuel Smeria 19.4 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
Jerome 14.1 4
Manuel Smeria 19.4 5 This tutorial shows you how to tune your XWiki platform by replacing the default URL scheme with a shorter scheme.
Jerome 15.1 6
Jerome 14.1 7 {{info}}
8 A short URL is an URL without the ##xwiki/bin/view## parts.
9 {{/info}}
maalej 2.1 10
Dmitry Bakbardin 20.1 11 = I. Application name =
maalej 1.1 12
Jerome 14.1 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##).
maalej 1.1 14
Vincent Massol 47.1 15 == Deploying as ROOT ==
16
Vincent Massol 46.1 17 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##.
Guillaume Fenollar 43.1 18
Vincent Massol 46.1 19 Achieving this depends on the container, as there's no standard regarding the ROOT application (Refer to your container's documentation for more details).
20
21 Some examples:
Paul Libbrecht 51.1 22
Vincent Massol 46.1 23 * 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##).
Vincent Massol 26.1 24 * 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:
25 ** 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.
26 ** Rename the existing ##webapps/xwiki## directory into ##webapps/root##.
27 ** 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.
Vincent Massol 10.2 28
Vincent Massol 47.2 29 In addition, starting with XWiki 6.2.8/6.4.3/7.0 you must tell XWiki that it's deployed as ROOT by setting the ##xwiki.webapppath## to empty in your ##xwiki.cfg## configuration file as in:
Vincent Massol 26.1 30
Vincent Massol 46.1 31 {{code language="none"}}
32 xwiki.webapppath=
33 {{/code}}
34
35 The reason is that XWiki cannot guess the webapp context from the URL in this case. This seemed to work on previous versions but it was actually leading to errors from time to time, depending on what URL was used when doing the first request on the XWiki instance.
36
Vincent Massol 49.1 37 === When using the XWiki Debian Package ===
38
Ecaterina Moraru (Valica) 61.1 39 See [[Installation using Debian (.DEB) packages>>Documentation.AdminGuide.Installation.InstallationViaAPT.WebHome||anchor="HXWikiasrootwebapp28shortURLs29"]].
Vincent Massol 49.1 40
Dmitry Bakbardin 20.1 41 = II. Servlet mapping name =
maalej 1.1 42
Vincent Massol 29.1 43 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).
maalej 1.1 44
Vincent Massol 35.1 45 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):
Guillaume Fenollar 43.1 46
Vincent Massol 29.1 47 * ##/resources/*## and ##/skins/*##: Statically served resources. These need to be served directly as static resources.
Vincent Massol 35.1 48 * ##/rest/*##: REST resources, served by the XWiki REST Servlet
Marius Dumitru Florea 65.1 49 * ##/xmlrpc/*##: XML-RPC resources, served by the XWiki XMLRPC Servlet {{warning}}Not part of XWiki anymore since 7.3{{/warning}}
50 * ##/resources/~*~*/*.gwtrpc##: GWT-RPC calls, served by the XWiki GWT Servlet {{warning}}Not part of XWiki anymore since 9.7RC1{{/warning}}
51 * ##/webdav/*##: WebDav calls, served by the XWiki WebDAV Servlet {{warning}}Not part of XWiki anymore since 8.0M1{{/warning}}
52 * ##/XWikiService##: Another XWiki GWT Servlet {{warning}}Not part of XWiki anymore since 9.7RC1{{/warning}}
Vincent Massol 29.1 53 * ##/redirect##: The XWiki Redirect Servlet used to redirect to the home page when no page is specified in the URL
maalej 1.1 54
Vincent Massol 38.1 55 There are various alternate to achieve this:
Dmitry Bakbardin 20.1 56
Vincent Massol 38.1 57 {{toc scope="local"/}}
58
Vincent Massol 37.1 59 {{info}}
Ecaterina Moraru (Valica) 62.1 60 You might be tempted to configure just your XWiki's ##web.xml## file [[but this won't work>>Documentation.AdminGuide.ShortURLs.ShortURLsInvalid.WebHome]].
Vincent Massol 37.1 61 {{/info}}
62
Vincent Massol 29.1 63 == UrlRewriteFilter ==
64
Guillaume Fenollar 43.1 65 {{info}}
Thomas Mortagne 59.1 66 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>>https://jira.xwiki.org/browse/XWIKI-9430]].
Guillaume Fenollar 43.1 67 {{/info}}
Vincent Massol 29.1 68
Vincent Massol 36.1 69 "UrlRewriteFilter" is a [[framework offering a Servlet Filter>>http://www.tuckey.org/urlrewrite/]] allowing to rewrite URLs.
70
71 Install steps:
Guillaume Fenollar 43.1 72
Vincent Massol 36.1 73 1. [[Download the JAR>>http://www.tuckey.org/urlrewrite/]] and put it in ##WEB-INF/lib##
Vincent Massol 64.1 74 1. Edit your ##WEB-INF/web.xml## and add the ##<filter>## and ##<filter-mapping>## definitions [[as documented>>http://www.tuckey.org/urlrewrite/]]. Make sure to have them first so that they're executed before any other XWiki filter.
slauriere 67.1 75 1. Drop the following content below in a file at ##WEB-INF/urlrewrite.xml##:(((
Vincent Massol 63.1 76 Note that this is just an example and you should tune it depending on what you wish to achieve. Its principle is very simple: it takes some URL format you wish to have and convert those URLs into the format that XWiki expects in input, and, in output, it does the opposite and converts the XWiki format into the format you wish to have.
77
78 The example below expects URLs without a ##/bin## and thus adds it so that XWiki has it when it processes URLs and in output, removes the ##/bin## so that generated URLs are without ##/bin##.
79
Jerome 14.1 80 {{code language="xml"}}
Vincent Massol 29.1 81 <?xml version="1.0" encoding="utf-8"?>
82 <!DOCTYPE urlrewrite PUBLIC "-//tuckey.org//DTD UrlRewrite 4.0//EN"
83 "http://www.tuckey.org/res/dtds/urlrewrite4.0.dtd">
Vincent Massol 42.1 84 <urlrewrite decode-using="null">
Vincent Massol 29.1 85
86 <rule>
87 <note>
88 Ensure that URLs ending with .gwtrpc are not modified.
Vincent Massol 62.5 89 Note: Not needed with XWiki 9.7+ since the GWT editor has been removed.
Vincent Massol 29.1 90 </note>
91 <from>^/(.*)\.gwtrpc$</from>
92 <to type="forward" last="true">-</to>
93 </rule>
94
95 <rule>
96 <note>
Vincent Massol 48.2 97 Ensure that URLs that must not be served by the Struts Servlet are not modified.
Vincent Massol 29.1 98 </note>
Martin Hamant 69.1 99 <from>^/((bin|resources|skins|asyncrenderer|rest|webdav|xmlrpc|wiki|jcaptcha|webjars)/(.*)|robots\.txt)$</from>
Vincent Massol 29.1 100 <to type="forward" last="true">-</to>
101 </rule>
102
103 <rule>
104 <note>
105 For all other URLs we prepend the "/bin/" prefix so that they get routed to the XWiki Action Servlet.
106 </note>
107 <from>^/(.*)$</from>
108 <to type="forward">/bin/$1</to>
109 </rule>
110
Vincent Massol 32.1 111 <outbound-rule>
112 <note>
Vincent Massol 48.1 113 Rewrite outbound URLs to remove the "/bin" part when there are two paths after it.
Vincent Massol 32.1 114 </note>
115 <from>/bin/(.*)/(.*)$</from>
116 <to>/$1/$2</to>
117 </outbound-rule>
118
Vincent Massol 48.1 119 <outbound-rule>
120 <note>
121 Rewrite outbound URLs to remove the "/bin" part when there's a single path after it.
122 </note>
123 <from>/bin/(.*)$</from>
124 <to>/$1</to>
125 </outbound-rule>
126
127 <outbound-rule>
128 <note>
129 Rewrite outbound URLs to remove the "/bin" part it's the last path.
130 </note>
131 <from>/bin$</from>
132 <to>/</to>
133 </outbound-rule>
134
Vincent Massol 29.1 135 </urlrewrite>
136 {{/code}}
Vincent Massol 36.1 137 )))
Vincent Massol 29.1 138
Anca Luca 45.1 139 **Note**: for debugging of URL Rewrite filter, set the ##logLevel## parameter as described in http://urlrewritefilter.googlecode.com/svn/trunk/src/doc/manual/4.0/index.html#filterparams (using the value ##sysout:DEBUG##, the logs can be read in tomcat logs).
140
Vincent Massol 39.1 141 == Apache ==
Jerome 16.1 142
Vincent Massol 39.1 143 Strategy:
Guillaume Fenollar 43.1 144
Marius Dumitru Florea 65.1 145 * Tell Apache that ##/skins## and ##/resources## URLs (except for ##/resources/~*~*/*.gwtrpc## ones in XWiki <9.7RC1) are served statically so that they don't go through the Servlet container
146 * Configure ##web.xml## so that ##/*## URLs go through the Struts Servlet and (for XWiki <9.7RC1) so that ##/resources/~*~*/*.gwtrpc## URLs go through the GWT Servlet
Vincent Massol 39.1 147 * Tell XWiki to not generate URLs with ##bin## in the path
Sergiu Dumitriu 4.1 148
Vincent Massol 39.1 149 Configuration steps:
Guillaume Fenollar 43.1 150
Vincent Massol 39.1 151 * Setup the following Apache configuration:(((
152 {{code language="apache"}}
Manuel Smeria 19.4 153 Alias /skins /usr/local/xwiki/skins
154 Alias /resources /usr/local/xwiki/resources
Jerome 19.1 155
Vincent Massol 34.1 156 RewriteEngine on
157
158 RewriteRule ^/+skins - [L]
159 RewriteCond %{REQUEST_URI} !\.gwtrpc$
160 RewriteRule ^/+resources($|/.*) - [L]
161
162 RewriteRule .* http://localhost:8080%{REQUEST_URI} [P,L]
163 ProxyPassReverse / http://localhost:8080/
164 {{/code}}
Vincent Massol 39.1 165 )))
Vincent Massol 41.1 166 * Edit ##web.xml## and add:(((
Vincent Massol 39.1 167 {{code language="xml"}}
168 <servlet-mapping>
169 <servlet-name>action</servlet-name>
170 <url-pattern>/*</url-pattern>
171 </servlet-mapping>
172 {{/code}}
173 )))
Marius Dumitru Florea 65.1 174 * For XWiki <9.7RC1 edit ##web.xml## and replace the existing mapping:(((
Vincent Massol 39.1 175 {{code language="xml"}}
176 <servlet-mapping>
177 <servlet-name>gwtrpc</servlet-name>
178 <url-pattern>*.gwtrpc</url-pattern>
179 </servlet-mapping>
180 {{/code}}
Vincent Massol 34.1 181
Vincent Massol 41.2 182 by
Vincent Massol 34.1 183
Vincent Massol 39.1 184 {{code language="xml"}}
185 <servlet-mapping>
186 <servlet-name>gwtrpc</servlet-name>
187 <url-pattern>/resources/*</url-pattern>
188 </servlet-mapping>
189 {{/code}}
190 )))
191 * Add the following in ##xwiki.cfg## (empty value after the equal sign):(((
Jerome 14.1 192 {{code language="none"}}
Vincent Massol 39.1 193 xwiki.defaultservletpath=
Jerome 14.1 194 {{/code}}
Guillaume Fenollar 43.1 195 )))
Vincent Massol 39.1 196 * {{info}}Only for XWiki 5.2+{{/info}} Add the following in ##xwiki.properties## (empty value after the equal sign):(((
197 {{code language="none"}}
Guillaume Fenollar 43.1 198 url.standard.getEntityPathPrefix=
Vincent Massol 39.1 199 {{/code}}
200 )))
PaulHarris 12.1 201
Vincent Massol 39.1 202 {{warning}}
203 There's a regression in XWiki 5.1 that will prevent this to work correctly. To overcome it, we recommend that you upgrade to XWiki 5.2. If you cannot, you could do the following:
Vincent Massol 62.3 204
Vincent Massol 39.1 205 * Remove the 3 ##xwiki-platform-url-*## JARs you have in your ##WEB-INF/lib## directory and instead add the following:
206 ** http://maven.xwiki.org/releases/org/xwiki/platform/xwiki-platform-url-api/5.2-milestone-2/xwiki-platform-url-api-5.2-milestone-2.jar
207 ** http://maven.xwiki.org/releases/org/xwiki/platform/xwiki-platform-url-container/5.2-milestone-2/xwiki-platform-url-container-5.2-milestone-2.jar
208 ** http://maven.xwiki.org/releases/org/xwiki/platform/xwiki-platform-url-standard/5.2-milestone-2/xwiki-platform-url-standard-5.2-milestone-2.jar
209 * Edit your ##xwiki.properties## file and add (no value after the equal sign):(((
Dmitry Bakbardin 23.1 210 {{code}}
Vincent Massol 39.1 211 url.standard.entityPathPrefix=
Dmitry Bakbardin 23.1 212 {{/code}}
Vincent Massol 39.1 213 )))
214 {{/warning}}
Dmitry Bakbardin 23.1 215
Dmitry Bakbardin 24.1 216
Dmitry Bakbardin 20.1 217 = III. Struts action name =
Jerome 14.1 218
Vincent Massol 50.2 219 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.
Manuel Smeria 19.4 220
Vincent Massol 50.2 221 It's possible to configure XWiki to allow omitting this action when you wish to imply ##view## and also to have XWiki generate URLs without the ##view## action. This is achieved by editing ##xwiki.cfg## and setting {{code language="none"}}xwiki.showviewaction=0{{/code}}.
Manuel Smeria 19.4 222
Vincent Massol 50.2 223 {{info}}
224 Before XWiki 7.2 and Nested Pages, XWiki was supporting dropping ##view## in the URL without changing the configuration. However this was broken in 7.2 in order to support Nested Pages.
225 {{/info}}
226
Dmitry Bakbardin 20.1 227 = IV. Error Page =
Manuel Smeria 19.4 228
Jerome 14.1 229 At the ##WEB-INF/web.xml##, the ##location## of the 404 error code needs to be changed accordingly. For example:
230
231 {{code language="xml"}}
232 <error-page>
mingfai 9.1 233 <error-code>404</error-code>
234 <!--<location>/xwiki/bin/view/Main/DocumentDoesNotExist</location>-->
235 <location>/bin/Main/DocumentDoesNotExist</location>
236 </error-page>
Jerome 14.1 237 {{/code}}
mingfai 9.1 238
Dmitry Bakbardin 20.1 239 = V. Conclusion =
Sergiu Dumitriu 4.1 240
241 After performing all these changes, you should be able to access documents with URLs like:
Jerome 14.1 242
Sergiu Dumitriu 4.1 243 * server.com/Space/Document
244 * server.com/Space/ (pointing to Space.WebHome)
245 * server.com/Document (pointing to Main.Document)
246 * server.com/ will show Main.WebHome, without any redirect.
247
Vincent Massol 5.1 248 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.
Valdis Vitolins 54.1 249
250
251 = Other solutions =
252
253 Some XWiki users have contributed other solutions but they've not been verified by a XWiki Development Team member at this stage so use at your own risk ;)
254
Ecaterina Moraru (Valica) 60.8 255 * [[Lighttpd + Jetty>>platform:Main.ShortURLsLighttpdJetty]]
Valdis Vitolins 58.1 256 * [[Apache + Tomcat>>http://odo.lv/Recipes/XWikiShortURLs?language=en]]

Get Connected