Configure Short URLs with Nginx
Last modified by Eleni Cojocariu on 2026/10/30 18:38
Content
Steps
Make Nginx rewrite the path in front of XWiki so that URLs stop carrying the /bin/ servlet mapping, the approach to take when the instance is already behind Nginx, as described in Short URLs.
- Serve /skins and /resources statically so that they never reach the servlet container, pointing the aliases at your own exploded XWiki web application.
location /skins { alias /usr/lib/xwiki/skins; } location /resources { alias /usr/lib/xwiki/resources; } - Strip /bin from incoming URLs and pass everything else to XWiki, keeping the proxy_set_header directives of your HTTP Reverse Proxy for XWiki configuration.
# Answer the old "/bin" URLs with a redirect to the short form. location /bin { rewrite ^/bin/(.*)$ /$1 permanent; } # The container redirects the browser for "/", so send it to the home page instead. location = / { return 301 $scheme://$server_name/Main; } # Everything else goes to the servlet container. location / { proxy_pass http://localhost:8080/; } - Map the action servlet to /* in WEB-INF/web.xml.
<servlet-mapping> <servlet-name>action</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> - Set xwiki.defaultservletpath to an empty value in xwiki.cfg, the key described with its xwiki.properties counterpart on URL Configuration Properties.
xwiki.defaultservletpath= - Restart Nginx and XWiki.
- Open any page and read its URL. The servlet mapping is gone, and the old URLs still resolve through a redirect that the browser follows.
before http://server.com/bin/view/Sandbox/WebHome after http://server.com/view/Sandbox/WebHome
FAQ
Why do attachment uploads fail with error 413?
Nginx caps the size of a request body. Add client_max_body_size 0 to the server block to lift the cap.
Do my old /bin/ URLs still work?
Yes. The location /bin block answers them with a permanent redirect to the short form.
Can I alias only some /resources subdirectories?
No. Alias the whole tree, or any resource path you did not list goes through the servlet container instead of being served statically.