Wiki source code of Switch to Domain-Based URLs

Last modified by Eleni Cojocariu on 2026/11/16 18:38

Show last authors
1 XWiki writes path-based URLs by default because that mode needs no name resolution at all, so switch a [[wiki farm>>doc:documentation.xs.admin.wikis.WebHome]] to domain-based URLs only once every wiki is meant to have a hostname of its own.
2
3 Before you start, make sure of the following.
4
5 * Each wiki's hostname resolves to the server, through DNS or through the server's hosts file. Domain-based URLs cannot work without it, since the hostname is what carries the wiki.
6 * You can edit the files under ##WEB-INF/## and restart the instance.
7 * You are an administrator of the main wiki, which is where the wiki descriptors live.
8
9 1. Set the URL form to domain-based in ##WEB-INF/xwiki.properties##:(((
10 {{code language="properties"}}
11 url.standard.multiwiki.isPathBased = false
12 {{/code}}
13 )))
14 1. Set it a second time in ##WEB-INF/xwiki.cfg##:(((
15 {{code language="properties"}}
16 xwiki.virtual.usepath=0
17 {{/code}}
18
19 Both files are needed: the factory that builds links and the filter that rewrites form submissions read the ##xwiki.cfg## key and nothing else, so changing only the first leaves part of the instance writing path-based URLs.
20 )))
21 1. Restart XWiki, so that both files are read again.
22 1. Open the Wiki Index from the Applications panel and select the Edit action of the wiki you are giving a hostname to, which opens its descriptor:(((
23 {{image reference="wiki-index.png" size="extra" alt="The Wiki Index listing the Home, Support and Training wikis with their description, owner and creation date, the Support row outlined and its Edit action at the right"/}}
24 )))
25 1. Set that wiki's alias to its hostname. The alias listed under "Wiki properties" is [[the one XWiki writes into every link it generates>>doc:documentation.xs.admin.urls.url-resolution.WebHome]] for the wiki, and on a farm that has been running path-based it still holds the bare wiki id:(((
26 {{image reference="wiki-default-alias.png" size="extra" alt="The Wiki properties section of the Support wiki descriptor, the Alias row outlined and holding the bare wiki id support"/}}
27
28 Change it on the descriptor page itself, through "Edit" then "Objects": open ##XWikiServerClass 0## and set its ##Server## field. The wiki's administration does not offer it.
29
30 {{warning}}
31 Adding a hostname under "Create new alias" does not do this. An extra alias only makes the wiki //reachable// under that name, so a wiki left with a bare id keeps writing links that resolve nowhere:
32
33 {{code language="none"}}
34 http://support/xwiki/bin/view/Main/
35 {{/code}}
36 {{/warning}}
37 )))
38 1. Add every further hostname the wiki has to answer on under "Create new alias":(((
39 {{image reference="wiki-alias.png" size="extra" alt="The Create new alias section of a wiki descriptor, with the empty Alias field outlined and the Create button next to it"/}}
40 )))
41 1. Check that the wiki now lists every one of its hostnames under "View aliases", and open it at one of them:(((
42 {{image reference="wiki-aliases.png" size="extra" alt="The View aliases section of the support wiki descriptor showing the alias support.example.org outlined, with its description, homepage and a Delete button"/}}
43
44 {{code language="none"}}
45 http://support.example.org/xwiki/bin/view/Main/WebHome
46 {{/code}}
47
48 The wiki creation wizard proposes a default alias of its own in domain-based mode, built from the wiki id and the suffix set in ##WEB-INF/xwiki.properties##, so set it to the domain the farm's wikis live under:
49
50 {{code language="properties"}}
51 wiki.alias.suffix = example.org
52 {{/code}}
53 )))

Get Connected