Short XWiki URLs
This tutorial shows you how to tune your XWiki platform by replacing the default URL scheme with a shorter scheme.
I. Application name
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).
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 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.
II. Servlet mapping name
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.
2.1. Original Instructions
2.1.1. Container setup
In Jetty, the container shipped with the XWiki installer, you will have to write something like:
<servlet-name>defaultSkins</servlet-name>
<servlet-class>org.mortbay.jetty.servlet.DefaultServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>defaultSkins</servlet-name>
<url-pattern>/skins/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>defaultSkins</servlet-name>
<url-pattern>/resources/*</url-pattern>
</servlet-mapping>
In Tomcat, the default servlet does not accept a parameter for changing the resource base, so you will need to write another default servlet.
2.1.2. Container setup alternative: front-end by-pass
Alternatively, you could by-pass 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:
Alias /resources /usr/local/xwiki/resources
ProxyPass /skins/ !
ProxyPass /resources/ !
2.2. Struts servlet mapping
The second thing to do is to copy the mapping for the Struts servlet to also be activated for /, like:
<servlet-name>action</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
Be sure to leave the other mappings in place, so that /bin/ works, too.
Tthe last thing that must be changed is the default mapping used by the URL factory, by adding this piece of code in xwiki.cfg: xwiki.defaultservletpath=.
2.3. Specific Lighttpd + Jetty Instructions
The original instructions might work for you if you don't use the WYSIWYG editor. It did not work for me and this is what I had to do:
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:
- /resources/* --> static content
- /skins/* --> static content
- *.gwtrpc --> a servlet
- everything else --> other servlets
The problem is that .gwtrpc files are in the /resources/ folder, and the /resources/* mapping will always have a higher priority than *.gwtrpc due to the way structs works.
So, we have to cheat a bit, and offload the static content to the webserver, which does have a powerful route-map configuration.
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)):
# ensure all requests for .gwtrpc files go through to java server
# we can put this rule first as a higher priority, which java couldn't do
$HTTP["url"] =~ "\.gwtrpc$" {
proxy.server = ( "" => (( "host" => "127.0.0.1", "port" => 8080 )))
}
# otherwise, we can handle the static resources
else $HTTP["url"] =~ "^/resources/" {
alias.url += ( "/resources" => "/usr/share/jetty/webapps/root/resources" )
}
# otherwise, we can handle the static resources
else $HTTP["url"] =~ "^/skins/" {
alias.url += ( "/skins" => "/usr/share/jetty/webapps/root/skins" )
}
# and here is the primary server
else $HTTP["host"] =~ "^www\.domain\.com$" {
proxy.server = ( "" => (( "host" => "127.0.0.1", "port" => 8080 )))
}
}
# redirect anything.domain.com to www.domain.com
else $HTTP["host"] =~ "\.domain\.com$" {
url.redirect = ( "^/(.*)" => "http://www.domain.com/$1" )
server.name = "www.domain.com"
}
# redirect domain.com to www.domain.com
else $HTTP["host"] =~ "domain\.com$" {
url.redirect = ( "^/(.*)" => "http://www.domain.com/$1" )
server.name = "www.domain.com"
}
So lighttpd will serve any static content unless it has .gwtrpc on the end of the URL.
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).
root /var/lib/tomcat7/webapps/ROOT;
}
location /resources/ {
try_files $uri $uri/ @fallback;
root /var/lib/tomcat7/webapps/ROOT;
}
location @fallback {
proxy_pass http://localhost:8080;
}
In the example above XWiki is set as ROOT application in Tomcat. Change path to your XWiki application accordingly.
Then in web.xml, I changed the gwtrpc mapping to:
<servlet-name>gwtrpc</servlet-name>
<url-pattern>/resources/*</url-pattern>
<url-pattern>/skins/*</url-pattern>
</servlet-mapping>
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.
Now, as described above, add a rule to catch everything else and redirect it to your xwiki servlet:
<servlet-name>action</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
The last thing that must be changed is the default mapping used by the URL factory, by adding this piece of code in xwiki.cfg: xwiki.defaultservletpath=.
2.4. Alternative: Changing the mapping name
If removing the /bin part is not possible in your environment, you can still rename it to something less technical, and which would better fit your site, like /wiki. To do this, you must first add a mapping for the new path, as in:
<servlet-name>action</servlet-name>
<url-pattern>/wiki/*</url-pattern>
</servlet-mapping>
This means that the wiki now accepts requests through this mapping.
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:
<servlet-name>redirectHomeServlet</servlet-name>
<servlet-class>com.xpn.xwiki.web.HomePageRedirectServlet</servlet-class>
<!-- Uncomment and edit this if you want to redirect to a different home page, or if you have different mappings.
Note: the URL should not start with /, because it allows the context name to be changed. If it starts with /,
then it should be an absolute URL, including the application context path. -->
<init-param>
<description>The address to redirect to when the client hits the root of the application.</description>
<param-name>homePage</param-name>
<param-value>wiki/</param-value>
</init-param>
</servlet>
Also change the default mapping used by the URL factory, by adding this in xwiki.cfg: xwiki.defaultservletpath=wiki/.
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 these settings:
RedirectMatch ^/xwiki/$ /xwiki/wiki/
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.
III. Struts action name
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.
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: xwiki.showviewaction=0.
IV. Error Page
At the WEB-INF/web.xml, the location of the 404 error code needs to be changed accordingly. For example:
<error-code>404</error-code>
<!--<location>/xwiki/bin/view/Main/DocumentDoesNotExist</location>-->
<location>/bin/Main/DocumentDoesNotExist</location>
</error-page>
V. Conclusion
After performing all these changes, you should be able to access documents with URLs like:
- server.com/Space/Document
- server.com/Space/ (pointing to Space.WebHome)
- server.com/Document (pointing to Main.Document)
- server.com/ will show Main.WebHome, without any redirect.
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.
