Wiki source code of Switch to Domain-Based URLs
Last modified by Eleni Cojocariu on 2026/11/16 18:38
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 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 | ))) |