HTTPS for XWiki in Docker
Explanation
The XWiki Docker image is a standard Apache Tomcat container serving plain HTTP on port 8080, which is the only port it exposes. It ships neither a certificate nor an HTTPS connector, so HTTPS is added the standard Tomcat way, either outside the container or inside it.
Terminating TLS in a reverse proxy placed in front of the container is the recommended option. XWiki stays a plain HTTP backend, reachable only on the internal Docker network, and the proxy is where automated certificate issuance and renewal live, for example Let's Encrypt through certbot, Traefik or Caddy, so renewing a certificate never involves the XWiki container at all. Setting the proxy up is covered by HTTP Reverse Proxy for XWiki. One point is specific to the XWiki image, though. Tomcat ignores the X-Forwarded-* headers sent by the proxy unless it is told to trust them with a RemoteIpValve, so without that valve XWiki keeps generating plain HTTP URLs even though visitors arrived over HTTPS. Configure XWiki in Docker Behind a Reverse Proxy covers that part.
Terminating TLS inside the container is the alternative when there is no reverse proxy in front of XWiki. Tomcat then needs an HTTPS connector and a keystore of its own, and its HTTPS port has to be published to the host, as described in Add an HTTPS Connector to Tomcat for XWiki in Docker.
The URLs XWiki Generates
Once Tomcat sees the incoming requests as HTTPS, either through the proxy's forwarded headers or through its own HTTPS connector, XWiki generates HTTPS URLs on its own: as long as xwiki.url.protocol is left empty in xwiki.cfg, the protocol of the URLs generated during a request is the one the client used. Two properties of xwiki.cfg are worth knowing about:
- xwiki.url.protocol forces the protocol of every generated external URL, whatever the request says. Setting it to https works around a proxy whose forwarded headers are not honored rather than fixing it, so prefer making Tomcat see the right scheme.
- xwiki.home sets the base URL of the main wiki: scheme, domain, optional port and trailing slash, for example
https://wiki.example.com/. XWiki needs it for the URLs it generates outside of a request, such as the links in notification emails, where there is no client scheme to derive.
To change these values in the image, mount your own xwiki.cfg as described in Configuration Files in the XWiki Docker Image.
FAQ
Does the image expose an HTTPS port?
No. The image exposes 8080 only, serving plain HTTP, exactly like the Tomcat image it is based on. HTTPS is added either by a reverse proxy in front of the container, or by adding an HTTPS connector to Tomcat and publishing its port yourself.
Why does XWiki still generate plain HTTP URLs behind my HTTPS reverse proxy?
Because Tomcat ignores the X-Forwarded-* headers unless it is told to trust them. XWiki then sees the plain HTTP request the proxy made and generates http URLs, which typically shows up as redirects falling back to plain HTTP. Declaring a RemoteIpValve in the Tomcat configuration mounted into the container fixes it.
Why do the generated URLs carry the HTTPS scheme but the wrong port?
Because the scheme was corrected but the port was not, giving URLs such as https://wiki.example.com:80/: they carry the public scheme while still carrying Tomcat's internal port. The RemoteIpValve rewrites the scheme, the secure flag and the server port together, which is why configuring it is preferable to forcing xwiki.url.protocol.
Do I need a certificate inside the XWiki container when using a reverse proxy?
No. TLS is terminated at the proxy, and the container only serves plain HTTP on the internal Docker network. Certificate issuance and renewal, with certbot, Traefik or Caddy for instance, all happen at the proxy, and the XWiki container does not need to be restarted when a certificate is renewed.
More
To find more about the current topic, you can search or use the table below and filter the columns to narrow your choices.
