Skip to Content

Wiki source code of Short URLs

Version 62.5 by Vincent Massol on 2017/11/21
Show last authors
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 == Deploying as ROOT ==
16
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##.
18
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:
22
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##).
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.
28
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:
30
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
37 === When using the XWiki Debian Package ===
38
39 See [[Installation using Debian (.DEB) packages>>Documentation.AdminGuide.Installation.InstallationViaAPT.WebHome||anchor="HXWikiasrootwebapp28shortURLs29"]].
40
41 = II. Servlet mapping name =
42
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).
44
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):
46
47 * ##/resources/*## and ##/skins/*##: Statically served resources. These need to be served directly as static resources.
48 * ##/rest/*##: REST resources, served by the XWiki REST Servlet
49 * ##/xmlrpc/*##: XML-RPC resources, served by the XWiki XMLRPC Servlet {{warning}}Not part of XE anymore since 7.3{{/warning}}
50 * ##/resources/~*~*/*.gwtrpc##: GWT-RPC calls, served by the XWiki GWT Servlet
51 * ##/webdav/*##: WebDav calls, served by the XWiki WebDAV Servlet
52 * ##/XWikiService##: Another XWiki GWT Servlet
53 * ##/redirect##: The XWiki Redirect Servlet used to redirect to the home page when no page is specified in the URL
54
55 There are various alternate to achieve this:
56
57 {{toc scope="local"/}}
58
59 {{info}}
60 You might be tempted to configure just your XWiki's ##web.xml## file [[but this won't work>>Documentation.AdminGuide.ShortURLs.ShortURLsInvalid.WebHome]].
61 {{/info}}
62
63 == UrlRewriteFilter ==
64
65 {{info}}
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]].
67 {{/info}}
68
69 "UrlRewriteFilter" is a [[framework offering a Servlet Filter>>http://www.tuckey.org/urlrewrite/]] allowing to rewrite URLs.
70
71 Install steps:
72
73 1. [[Download the JAR>>http://www.tuckey.org/urlrewrite/]] and put it in ##WEB-INF/lib##
74 1. Edit your ##WEB-INF/web.xml## and add the ##<filter>## and ##filter-mapping## definitions [[as documented>>http://www.tuckey.org/urlrewrite/]]
75 1. Drop the following content in a file at ##WEB-INF/urlrewrite.xml## (This is just an example, adjust for your needs):(((
76 {{code language="xml"}}
77 <?xml version="1.0" encoding="utf-8"?>
78 <!DOCTYPE urlrewrite PUBLIC "-//tuckey.org//DTD UrlRewrite 4.0//EN"
79 "http://www.tuckey.org/res/dtds/urlrewrite4.0.dtd">
80 <urlrewrite decode-using="null">
81
82 <rule>
83 <note>
84 Ensure that URLs ending with .gwtrpc are not modified.
85 Note: Not needed with XWiki 9.7+ since the GWT editor has been removed.
86 </note>
87 <from>^/(.*)\.gwtrpc$</from>
88 <to type="forward" last="true">-</to>
89 </rule>
90
91 <rule>
92 <note>
93 Ensure that URLs that must not be served by the Struts Servlet are not modified.
94 </note>
95 <from>^/((bin|resources|skins|rest|webdav|xmlrpc|wiki|webjars)/(.*)|robots\.txt)$</from>
96 <to type="forward" last="true">-</to>
97 </rule>
98
99 <rule>
100 <note>
101 For all other URLs we prepend the "/bin/" prefix so that they get routed to the XWiki Action Servlet.
102 </note>
103 <from>^/(.*)$</from>
104 <to type="forward">/bin/$1</to>
105 </rule>
106
107 <outbound-rule>
108 <note>
109 Rewrite outbound URLs to remove the "/bin" part when there are two paths after it.
110 </note>
111 <from>/bin/(.*)/(.*)$</from>
112 <to>/$1/$2</to>
113 </outbound-rule>
114
115 <outbound-rule>
116 <note>
117 Rewrite outbound URLs to remove the "/bin" part when there's a single path after it.
118 </note>
119 <from>/bin/(.*)$</from>
120 <to>/$1</to>
121 </outbound-rule>
122
123 <outbound-rule>
124 <note>
125 Rewrite outbound URLs to remove the "/bin" part it's the last path.
126 </note>
127 <from>/bin$</from>
128 <to>/</to>
129 </outbound-rule>
130
131 </urlrewrite>
132 {{/code}}
133 )))
134
135 **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).
136
137 == Apache ==
138
139 Strategy:
140
141 * Tell Apache that ##/skins## and ##/resources## URLs (except for ##/resources/~*~*/*.gwtrpc## ones) are served statically so that they don't go through the Servlet container
142 * Configure ##web.xml## so that ##/*## URLs go through the Struts Servlet and so that ##/resources/~*~*/*.gwtrpc## URLs go through the GWT Servlet
143 * Tell XWiki to not generate URLs with ##bin## in the path
144
145 Configuration steps:
146
147 * Setup the following Apache configuration:(((
148 {{code language="apache"}}
149 Alias /skins /usr/local/xwiki/skins
150 Alias /resources /usr/local/xwiki/resources
151
152 RewriteEngine on
153
154 RewriteRule ^/+skins - [L]
155 RewriteCond %{REQUEST_URI} !\.gwtrpc$
156 RewriteRule ^/+resources($|/.*) - [L]
157
158 RewriteRule .* http://localhost:8080%{REQUEST_URI} [P,L]
159 ProxyPassReverse / http://localhost:8080/
160 {{/code}}
161 )))
162 * Edit ##web.xml## and add:(((
163 {{code language="xml"}}
164 <servlet-mapping>
165 <servlet-name>action</servlet-name>
166 <url-pattern>/*</url-pattern>
167 </servlet-mapping>
168 {{/code}}
169 )))
170 * Edit ##web.xml## and replace the existing mapping:(((
171 {{code language="xml"}}
172 <servlet-mapping>
173 <servlet-name>gwtrpc</servlet-name>
174 <url-pattern>*.gwtrpc</url-pattern>
175 </servlet-mapping>
176 {{/code}}
177
178 by
179
180 {{code language="xml"}}
181 <servlet-mapping>
182 <servlet-name>gwtrpc</servlet-name>
183 <url-pattern>/resources/*</url-pattern>
184 </servlet-mapping>
185 {{/code}}
186 )))
187 * Add the following in ##xwiki.cfg## (empty value after the equal sign):(((
188 {{code language="none"}}
189 xwiki.defaultservletpath=
190 {{/code}}
191 )))
192 * {{info}}Only for XWiki 5.2+{{/info}} Add the following in ##xwiki.properties## (empty value after the equal sign):(((
193 {{code language="none"}}
194 url.standard.getEntityPathPrefix=
195 {{/code}}
196 )))
197
198 {{warning}}
199 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:
200
201 * Remove the 3 ##xwiki-platform-url-*## JARs you have in your ##WEB-INF/lib## directory and instead add the following:
202 ** 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
203 ** 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
204 ** 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
205 * Edit your ##xwiki.properties## file and add (no value after the equal sign):(((
206 {{code}}
207 url.standard.entityPathPrefix=
208 {{/code}}
209 )))
210 {{/warning}}
211
212
213 = III. Struts action name =
214
215 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.
216
217 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}}.
218
219 {{info}}
220 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.
221 {{/info}}
222
223 = IV. Error Page =
224
225 At the ##WEB-INF/web.xml##, the ##location## of the 404 error code needs to be changed accordingly. For example:
226
227 {{code language="xml"}}
228 <error-page>
229 <error-code>404</error-code>
230 <!--<location>/xwiki/bin/view/Main/DocumentDoesNotExist</location>-->
231 <location>/bin/Main/DocumentDoesNotExist</location>
232 </error-page>
233 {{/code}}
234
235 = V. Conclusion =
236
237 After performing all these changes, you should be able to access documents with URLs like:
238
239 * server.com/Space/Document
240 * server.com/Space/ (pointing to Space.WebHome)
241 * server.com/Document (pointing to Main.Document)
242 * server.com/ will show Main.WebHome, without any redirect.
243
244 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.
245
246
247 = Other solutions =
248
249 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 ;)
250
251 * [[Lighttpd + Jetty>>platform:Main.ShortURLsLighttpdJetty]]
252 * [[Apache + Tomcat>>http://odo.lv/Recipes/XWikiShortURLs?language=en]]

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected