Configure Short URLs with Nginx

Last modified by Eleni Cojocariu on 2026/10/30 18:38

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.

  1. 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;
    }
  2. 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/;
    }
  3. Map the action servlet to /* in WEB-INF/web.xml.
    <servlet-mapping>
      <servlet-name>action</servlet-name>
      <url-pattern>/*</url-pattern>
    </servlet-mapping>
  4. Set xwiki.defaultservletpath to an empty value in xwiki.cfg, the key described with its xwiki.properties counterpart on URL Configuration Properties.
    xwiki.defaultservletpath=
  5. Restart Nginx and XWiki.
  6. 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.

Related

Get Connected