Apache Server Key Configurations
Reference
Apache HTTP Server forwards requests to XWiki through its mod_proxy module. The directives below are the ones a wiki needs; Configure Apache HTTP Server as a Proxy on a Linux OS and Configure Apache HTTP Server as a Proxy on a Windows OS assemble them into a complete VirtualHost, and Configure HTTPS for the Apache HTTP Proxy Server adds the HTTPS ones.
Proxy Directives
These go in the VirtualHost block that serves the wiki, on port 80 for a plain HTTP configuration and on port 443 for an HTTPS one.
| Directive | What it does |
|---|---|
<VirtualHost *:80> | Opens the block that handles every request arriving on port 80, on all network interfaces (*). |
| ServerName localhost | The host name this block answers for. Set it to the wiki's public domain, for example ServerName wiki.example.com. |
ErrorLog ${APACHE_LOG_DIR}/xwiki-error.log and CustomLog ${APACHE_LOG_DIR}/xwiki-access.log combined | Optional per-wiki log files, so that proxy problems can be told apart from the rest of the server's traffic. |
| RedirectMatch ^/$ /xwiki/ | Redirects the root URL to the wiki, so that http://localhost reaches XWiki without /xwiki being typed. See RedirectMatch. |
<Location /xwiki> with Require all granted | Grants access to the proxied path. See Require. |
| AllowEncodedSlashes NoDecode | Lets Apache forward URLs that contain an encoded slash (%2F) without decoding it, which XWiki page names can contain. The default is Off, under which Apache answers 404 for such URLs. See AllowEncodedSlashes. |
RequestHeader unset Forwarded, RequestHeader unset X-Forwarded-Host and RequestHeader unset X-Forwarded-Proto | Drops any forwarded header the client sent, before Apache appends its own. XWiki builds its URLs from the first value of these headers while Apache appends after the client's, so without the three lines a reader can make the wiki emit links for any host or scheme. Provided by mod_headers. See RequestHeader. |
| ProxyRequests Off | Disables the forward proxy, which a reverse proxy never uses and which would otherwise turn the server into an open proxy. See ProxyRequests. |
| ProxyPreserveHost On | Forwards the client's Host header to XWiki, so that XWiki builds URLs for the public domain rather than for localhost. See ProxyPreserveHost. |
ProxyPass /xwiki http://localhost:8080/xwiki nocanon upgrade=websocket | Forwards /xwiki to the Servlet Container. nocanon passes the path on raw, leaving characters such as ; and encoded slashes untouched; upgrade=websocket tunnels the WebSocket connections that realtime editing uses, and needs Apache HTTP Server 2.4.47 or later. See ProxyPass. |
ProxyPassReverse /xwiki http://localhost:8080/xwiki | Rewrites the Location header of the redirects XWiki returns, so that a redirect to localhost:8080 reaches the reader as one to the public URL. It takes no nocanon option, and silently ignores any third keyword written there rather than reporting it. See ProxyPassReverse. |
HTTPS Directives
These are added to the port 443 block, on top of the proxy directives above.
| Directive | What it does |
|---|---|
<VirtualHost *:443> | Opens the block that handles HTTPS requests. It carries the same proxy directives as the port 80 block, plus the ones below. |
| SSLEngine on | Enables TLS for this block. Provided by mod_ssl. |
| SSLCertificateFile /path/to/certificate | The server certificate presented to browsers during the TLS handshake. See SSLCertificateFile. |
| SSLCertificateKeyFile /path/to/privatekey | The private key matching that certificate. See SSLCertificateKeyFile. |
| RequestHeader set X-Forwarded-Proto "https" | Tells XWiki that the reader's request used HTTPS, which Apache would otherwise hide by forwarding it over plain HTTP. It goes after the three RequestHeader unset lines above, so that the value the wiki reads is the proxy's own. Provided by mod_headers. |
Redirection Directives
These go in the port 80 block, whose body they replace once HTTPS serves the wiki, so that a plain HTTP request is redirected instead of proxied.
| Directive | What it does |
|---|---|
| AllowEncodedSlashes NoDecode | Still required in a block that only redirects: without it Apache answers 404 for a URL holding an encoded slash instead of redirecting it. |
| RewriteEngine On | Enables the rewriting engine, without which no RewriteCond or RewriteRule is processed. Provided by mod_rewrite. |
RewriteCond %{REQUEST_URI} !^/\.well-known | Exempts /.well-known, where an ACME client such as certbot answers the challenge that issues and renews the certificate, and which therefore has to stay reachable over plain HTTP. |
RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R=301,L,NE] | Redirects everything else to the HTTPS address of the same URL. [R=301] makes it a permanent external redirect, [L] stops further rules being applied, and [NE] keeps the redirect from encoding a second time the %2F an XWiki page name can contain. See RewriteRule Flags. |
FAQ
How can I check whether Apache is running?
Open http://localhost in a browser: Apache's own default page means the server is running but is not forwarding to XWiki yet.
How do I serve the wiki on my own domain instead of localhost?
Set ServerName to that domain, for example ServerName wiki.example.com, and make sure the name resolves — a name that is not published in DNS has to be added to the hosts file of every machine that uses it.
Why does the wiki answer 404 through the proxy while port 8080 still works?
The proxied path does not match the wiki's context path: ProxyPass, ProxyPassReverse and <Location> all have to use the same /xwiki prefix as the Servlet Container.
Why does realtime editing not work through the proxy?
Its WebSocket connection is not being tunnelled: ProxyPass needs the upgrade=websocket option, on Apache HTTP Server 2.4.47 or later.
Why does importing a large XAR or uploading a large attachment answer 504?
Apache stops waiting for the Servlet Container after ProxyTimeout seconds, 60 by default, while the container is still working. Raise it in the VirtualHost, for example ProxyTimeout 600. See ProxyTimeout.
More
To find more about the current topic, you can search or use the table below and filter the columns to narrow your choices.
