Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{velocity filter="none"}} | ||
| 2 | {{html wiki=true clean=false}} | ||
| 3 | #startfloatingbox() | ||
| 4 | **Content** | ||
| 5 | |||
| 6 | {{toc /}} | ||
| 7 | |||
| 8 | #endfloatingbox() | ||
| 9 | {{/html}} | ||
| 10 | {{/velocity}} | ||
| 11 | |||
| 12 | = Short XWiki URLs = | ||
| 13 | |||
| 14 | This tutorial shows how to tune your XWiki platform by replacing the default URL scheme with a shorter scheme. | ||
| 15 | |||
| 16 | {{info}} | ||
| 17 | A short URL is an URL without the ##xwiki/bin/view## parts. | ||
| 18 | {{/info}} | ||
| 19 | |||
| 20 | == Application name == | ||
| 21 | |||
| 22 | 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##). | ||
| 23 | |||
| 24 | 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 again depends on the container, as there's no standard regarding the ROOT application. For example 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##). In Jetty, the default name is ##root##. Refer to your container's documentation for more details. | ||
| 25 | |||
| 26 | {{warning}} | ||
| 27 | Before XWiki Platform 1.3, the the ##display-name## parameter in ##web.xml## must also be changed to reflect the new application name. For example if you've deployed the XWiki webapp as ROOT then you'll need to have: | ||
| 28 | |||
| 29 | {{code language="xml"}}<display-name></display-name>{{/code}} | ||
| 30 | |||
| 31 | {{/warning}} | ||
| 32 | |||
| 33 | == Struts action name == | ||
| 34 | |||
| 35 | The third part, /view/, identifies the struts action that should process a request. So this tells what do 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. | ||
| 36 | |||
| 37 | 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, in ##xwiki.cfg## write: | ||
| 38 | |||
| 39 | {{code language="none"}} | ||
| 40 | xwiki.showviewaction=0 | ||
| 41 | {{/code}} | ||
| 42 | |||
| 43 | == Servlet mapping name == | ||
| 44 | |||
| 45 | 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. To get rid of /bin/, for the moment ##web.xml## must be changed in a container-dependent way, so that the container's default servlet is configured to serve the existing directories, like skins, yui, tinymce and wikieditor. | ||
| 46 | |||
| 47 | === Original Instructions === | ||
| 48 | |||
| 49 | In Jetty, the container shipped with the XWiki installer, you will have to write something like: | ||
| 50 | |||
| 51 | {{code language="xml"}} | ||
| 52 | <servlet> | ||
| 53 | <servlet-name>defaultSkins</servlet-name> | ||
| 54 | <servlet-class>org.mortbay.jetty.servlet.DefaultServlet</servlet-class> | ||
| 55 | <load-on-startup>1</load-on-startup> | ||
| 56 | </servlet> | ||
| 57 | <servlet-mapping> | ||
| 58 | <servlet-name>defaultSkins</servlet-name> | ||
| 59 | <url-pattern>/skins/*</url-pattern> | ||
| 60 | </servlet-mapping> | ||
| 61 | <servlet-mapping> | ||
| 62 | <servlet-name>defaultSkins</servlet-name> | ||
| 63 | <url-pattern>/resources/*</url-pattern> | ||
| 64 | </servlet-mapping> | ||
| 65 | {{/code}} | ||
| 66 | |||
| 67 | {{warning}} | ||
| 68 | If you are using jetty 1.7 or higher, the correct servlet-class is ##org.eclipse.jetty.servlet.DefaultServlet## | ||
| 69 | {{/warning}} | ||
| 70 | |||
| 71 | In Tomcat, the default servlet does not accept a parameter for changing the resource base, so you will need to write another default servlet. | ||
| 72 | |||
| 73 | The second thing to do, is to copy the mapping for the Struts servlet to also be activated for /, like: | ||
| 74 | |||
| 75 | {{code language="xml"}} | ||
| 76 | <servlet-mapping> | ||
| 77 | <servlet-name>action</servlet-name> | ||
| 78 | <url-pattern>/*</url-pattern> | ||
| 79 | </servlet-mapping> | ||
| 80 | {{/code}} | ||
| 81 | |||
| 82 | Be sure to leave the other mappings in place, so that /bin/ works, too. | ||
| 83 | |||
| 84 | And the last thing that must be changed is the default mapping used by the URL factory, by adding in ##xwiki.cfg##: | ||
| 85 | |||
| 86 | {{code language="none"}} | ||
| 87 | xwiki.defaultservletpath= | ||
| 88 | {{/code}} | ||
| 89 | |||
| 90 | {{warning}} | ||
| 91 | Before 1.7, the setting name was ##xwiki.defaultactionpath##. | ||
| 92 | {{/warning}} | ||
| 93 | |||
| 94 | === Specific Lighttpd + Jetty Instructions === | ||
| 95 | |||
| 96 | The original instructions MIGHT work for you, if you don't use the WYSIWYG editor. It did not work for me, this is what I had to do. | ||
| 97 | |||
| 98 | The problem is that you need to use Java Struts for the routing. They are not very powerful when it comes to the servlet-mapping configuration. We need to map: | ||
| 99 | |||
| 100 | * /resources/* ~-~-> static content | ||
| 101 | * /skins/* ~-~-> static content | ||
| 102 | * *.gwtrpc ~-~-> a servlet | ||
| 103 | * everything else ~-~-> other servlets | ||
| 104 | |||
| 105 | The problem is that .gwtrpc files are "in" the /resources folder, and as the /resources/* mapping will always be a higher priority than *.gwtrpc due to the way structs works. | ||
| 106 | |||
| 107 | So, we have to cheat a bit, and offload the static content to the webserver, which DOES have a powerful route-map configuration. | ||
| 108 | |||
| 109 | I use lighttpd, but I assume it can be done in other webservers. 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): | ||
| 110 | |||
| 111 | {{code language="none"}} | ||
| 112 | $HTTP["host"] =~ "^www\.domain\.com$" { | ||
| 113 | # ensure all requests for .gwtrpc files go through to java server | ||
| 114 | # we can put this rule first as a higher priority, which java couldn't do | ||
| 115 | $HTTP["url"] =~ "\.gwtrpc$" { | ||
| 116 | proxy.server = ( "" => (( "host" => "127.0.0.1", "port" => 8080 ))) | ||
| 117 | } | ||
| 118 | # otherwise, we can handle the static resources | ||
| 119 | else $HTTP["url"] =~ "^/resources/" { | ||
| 120 | alias.url += ( "/resources" => "/usr/share/jetty/webapps/root/resources" ) | ||
| 121 | } | ||
| 122 | # otherwise, we can handle the static resources | ||
| 123 | else $HTTP["url"] =~ "^/skins/" { | ||
| 124 | alias.url += ( "/skins" => "/usr/share/jetty/webapps/root/skins" ) | ||
| 125 | } | ||
| 126 | # and here is the primary server | ||
| 127 | else $HTTP["host"] =~ "^www\.domain\.com$" { | ||
| 128 | proxy.server = ( "" => (( "host" => "127.0.0.1", "port" => 8080 ))) | ||
| 129 | } | ||
| 130 | } | ||
| 131 | # redirect anything.domain.com to www.domain.com | ||
| 132 | else $HTTP["host"] =~ "\.domain\.com$" { | ||
| 133 | url.redirect = ( "^/(.*)" => "http://www.domain.com/$1" ) | ||
| 134 | server.name = "www.domain.com" | ||
| 135 | } | ||
| 136 | # redirect domain.com to www.domain.com | ||
| 137 | else $HTTP["host"] =~ "domain\.com$" { | ||
| 138 | url.redirect = ( "^/(.*)" => "http://www.domain.com/$1" ) | ||
| 139 | server.name = "www.domain.com" | ||
| 140 | } | ||
| 141 | {{/code}} | ||
| 142 | |||
| 143 | So lighttpd will serve any static content UNLESS it has .gwtrpc on the end of the URL. | ||
| 144 | |||
| 145 | Then in web.xml, I change the gwtrpc mapping to: | ||
| 146 | |||
| 147 | {{code language="xml"}} | ||
| 148 | <servlet-mapping> | ||
| 149 | <servlet-name>gwtrpc</servlet-name> | ||
| 150 | |||
| 151 | <url-pattern>/resources/*</url-pattern> | ||
| 152 | <url-pattern>/skins/*</url-pattern> | ||
| 153 | </servlet-mapping> | ||
| 154 | {{/code}} | ||
| 155 | |||
| 156 | 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 its ok. Note that only resources is required, but I did both anyway. | ||
| 157 | |||
| 158 | Now, as described above, add a rule to catch everything else and redirect it to our xwiki servlet. | ||
| 159 | |||
| 160 | {{code language="xml"}} | ||
| 161 | <servlet-mapping> | ||
| 162 | <servlet-name>action</servlet-name> | ||
| 163 | <url-pattern>/*</url-pattern> | ||
| 164 | </servlet-mapping> | ||
| 165 | {{/code}} | ||
| 166 | |||
| 167 | And the last thing that must be changed is the default mapping used by the URL factory, by adding in ##xwiki.cfg##: | ||
| 168 | |||
| 169 | {{code language="none"}} | ||
| 170 | xwiki.defaultservletpath= | ||
| 171 | {{/code}} | ||
| 172 | |||
| 173 | === Alternative: Changing the mapping name === | ||
| 174 | |||
| 175 | If removing the ##/bin## part is not possible in your environment, you can still rename it to something less technical, and which would fit better in your site, like ##/wiki##. To do this, you must first add a mapping for the new path, as in: | ||
| 176 | |||
| 177 | {{code language="xml"}} | ||
| 178 | <servlet-mapping> | ||
| 179 | <servlet-name>action</servlet-name> | ||
| 180 | <url-pattern>/wiki/*</url-pattern> | ||
| 181 | </servlet-mapping> | ||
| 182 | {{/code}} | ||
| 183 | |||
| 184 | This means that the wiki now accepts requests through this mapping. | ||
| 185 | |||
| 186 | {{info}} | ||
| 187 | This specific mapping (##/wiki##) should already be there, but you need to add a new one for other custom mappings. | ||
| 188 | {{/info}} | ||
| 189 | |||
| 190 | {{warning}} | ||
| 191 | The ##/wiki## mapping is reserved for multiwiki with path based wiki mapping setup, so use something else in this scenarion. It should work fine when multiwikis are disabled, or when only hostname wiki mapping is used. | ||
| 192 | {{/warning}} | ||
| 193 | |||
| 194 | Then you must make sure that accessing the application without a servlet in the path (as in ##http://server.com/xwiki/## when XWiki is not set as the ROOT application, or ##http://server.com/## if XWiki is the ROOT application) redirects to the right servlet. This involves changing the configuration for the ##redirect## servlet in web.xml; search for the declaration of the ##redirectHomeServlet##, uncomment the ##init-param## section, and adjust accordingly: | ||
| 195 | |||
| 196 | {{code language="xml"}} | ||
| 197 | <servlet> | ||
| 198 | <servlet-name>redirectHomeServlet</servlet-name> | ||
| 199 | <servlet-class>com.xpn.xwiki.web.HomePageRedirectServlet</servlet-class> | ||
| 200 | <!-- Uncomment and edit this if you want to redirect to a different home page, or if you have different mappings. | ||
| 201 | Note: the URL should not start with /, because it allows the context name to be changed. If it starts with /, | ||
| 202 | then it should be an absolute URL, including the application context path. --> | ||
| 203 | <init-param> | ||
| 204 | <description>The address to redirect to when the client hits the root of the application.</description> | ||
| 205 | <param-name>homePage</param-name> | ||
| 206 | <param-value>wiki/</param-value> | ||
| 207 | </init-param> | ||
| 208 | </servlet> | ||
| 209 | {{/code}} | ||
| 210 | |||
| 211 | Also change the default mapping used by the URL factory, by adding in xwiki.cfg: | ||
| 212 | |||
| 213 | {{code language="none"}} | ||
| 214 | xwiki.defaultservletpath=wiki/ | ||
| 215 | {{/code}} | ||
| 216 | |||
| 217 | Optionally, you can make sure that accessing the hostname without a path (as in ##http://server.com/##) redirects to the right servlet. This depends on your environment. In a Tomcat + Apache HTTPD + mod_redirect, just update the settings:## | ||
| 218 | |||
| 219 | {{code language="none"}} | ||
| 220 | RedirectMatch ^/$ /xwiki/wiki/ | ||
| 221 | RedirectMatch ^/xwiki/$ /xwiki/wiki/ | ||
| 222 | {{/code}} | ||
| 223 | |||
| 224 | In the default standalone distribution (with Jetty), the ROOT application only redirects to the ##/xwiki## application, so configuring the XWiki redirect servlet is enough if you don't change the application name. If you do, just edit the ##web.xml## of the ##root## webapp, uncomment the ##init-param## of the ##XWikiDispatcherServlet## and change the application name. | ||
| 225 | |||
| 226 | == Error Page == | ||
| 227 | |||
| 228 | At the ##WEB-INF/web.xml##, the ##location## of the 404 error code needs to be changed accordingly. For example: | ||
| 229 | |||
| 230 | {{code language="xml"}} | ||
| 231 | <error-page> | ||
| 232 | <error-code>404</error-code> | ||
| 233 | <!--<location>/xwiki/bin/view/Main/DocumentDoesNotExist</location>--> | ||
| 234 | <location>/bin/Main/DocumentDoesNotExist</location> | ||
| 235 | </error-page> | ||
| 236 | {{/code}} | ||
| 237 | |||
| 238 | == Conclusion == | ||
| 239 | |||
| 240 | After performing all these changes, you should be able to access documents with URLs like: | ||
| 241 | |||
| 242 | * server.com/Space/Document | ||
| 243 | * server.com/Space/ (pointing to Space.WebHome) | ||
| 244 | * server.com/Document (pointing to Main.Document) | ||
| 245 | * server.com/ will show Main.WebHome, without any redirect. | ||
| 246 | |||
| 247 | 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. |
