View source for Manual:Short URL/Apache

<languages />
{{Update
|part=Apache2 configuration instructions
|reason=They do not seem to have been tested and are poorly explained.
|date=18 Nov 2021
}}

[[File:ENWP-ShortURL.png|frame|{{dir|{{pagelang}}|left|right}}|<translate><!--T:62--> Wikipedia's short URLs.</translate>]]{{TOC|align=right}}
<translate><!--T:1--> These instructions help setup Short URLs on [[<tvar name=1>Special:MyLanguage/Apache configuration</tvar>|Apache]].</translate>
<translate><!--T:63--> The LiteSpeed webserver is Apache compatible and can be configured in relatively the same way.</translate>
<translate><!--T:64--> For information on what Short URLs are or to get instructions on configuration for other servers see <tvar name=2>{{ll|Manual:Short URL}}</tvar>.</translate>
<translate><!--T:65--> If you don't know what webserver you're using since you're using some sort of web hosting service, it's very likely that your host is using Apache.</translate>

{{Anchor|Plan}}
<translate>
== Setup == <!--T:2-->

<!--T:3-->
Before starting, you need to decide on the name of your virtual "short url" path.

<!--T:4-->
In this manual we'll recommend/assume the following. Remember to use your own paths if they are different.

<!--T:5-->
* The MediaWiki directory is located at: <tvar name=code1><code>/w</code></tvar>
* The desired short url format is: <tvar name=code2><code>/wiki/Page_title</code></tvar>

== Server config == <!--T:9-->

=== Find the right file === <!--T:10-->
</translate>
<translate><!--T:11--> The recommended way to set up short URLs in Apache is by editing the Apache config files.</translate>
<translate><!--T:69--> This requires that you have access to the server configuration.</translate>
<translate><!--T:70--> If you are on a shared host, you most likely don't and will need to use a <tvar name=hta1><code>.htaccess</code></tvar> file instead.</translate>
<translate><!--T:71--> Using <tvar name=hta2><code>.htaccess</code></tvar> files is less efficient and doesn't give you as much control when it comes to fancy setups with multiple domains but they are powerful enough to set up most short url configurations.</translate>
<translate><!--T:72--> LiteSpeed users should use the <tvar name=hta3><code>.htaccess</code></tvar> method.</translate>

<translate>
<!--T:12-->
Use the instructions in one of the following two sections, depending on whether you have root access or need to use <tvar name=hta><code>.htaccess</code></tvar> instead.

=== Find the Apache configuration file (root access) === <!--T:13-->

<!--T:14-->
The correct configuration file to edit for root configurations may be in one of a number of places.
</translate>

<translate><!--T:73--> The correct config file to edit is the one in <tvar name=code3><code>/etc/apache2/sites-available/</code></tvar> where the configuration for your wiki has been setup.</translate>
<translate><!--T:15--> Most linux distributions setup Apache with set of <tvar name=code1><code>sites-available/</code></tvar> and <tvar name=code2><code>sites-enabled/</code></tvar> folders setup.</translate>

<translate>
<!--T:74-->
If you haven't set one up and are using the default <tvar name=code4><code>/var/www</code></tvar> for your wiki setup then you can edit <tvar name=code5><code>/etc/apache2/sites-available/default</code></tvar>.
</translate>

<translate><!--T:16--> Don't forget to enable overrides by <tvar name=code><code>AllowOverride All</code></tvar> in <tvar name=1><code>/etc/apache2/apache2.conf</code></tvar>.</translate>
<translate><!--T:75--> It is disabled by default in Ubuntu 12.04 and Ubuntu 12.10.</translate>

<translate><!--T:17--> If your distribution does not have those directories, then you should edit the Apache configuration file directly.</translate>
<translate><!--T:76--> This file should be at <tvar name=code1><code>/etc/apache2/apache2.conf</code></tvar>.</translate>
<translate><!--T:77--> Note that it used to be named <tvar name=httpd1><code>httpd.conf</code></tvar>, if you have a <tvar name=httpd2><code>httpd.conf</code></tvar> and no <tvar name=apache><code>apache2.conf</code></tvar> then <tvar name=httpd3><code>httpd.conf</code></tvar> is the one you want to edit.</translate>

<translate>
<!--T:18-->
If your Apache config isn't in any of these spots you should consult the documentation for whatever system you used to install Apache, and find the location of the Apache configuration file.

<!--T:19-->
If you're on a shared host without access to Apache config files you'll have to use a .htaccess file instead.
</translate>

<translate><!--T:20--> In an Apache config file you will likely have a VirtualHost block containing your wiki. If you do have one then that is the location where your [[<tvar name=1>#Setting up the rewrite rules</tvar>|rewrite rules]] will go.</translate>
<translate><!--T:78--> RewriteRule config does not inherit so don't put these config options in the global config if you are using a VirtualHost.</translate>

<translate>
<!--T:21-->
After you've setup the config as above inside Apache you're going to need to restart Apache to make it apply the new config.
</translate>

* <translate><!--T:22--> If you are using Plesk or cPanel it should have a method of restarting the server.</translate>
* <translate><!--T:23--> From the command line the command is usually something like <tvar name=code1><code>apache2ctl graceful</code></tvar>, <tvar name=code2><code>apachectl graceful</code></tvar>, <tvar name=code3><code>/etc/init.d/apache2 restart</code></tvar> or as on the latest Fedora releases <tvar name=code4><code>systemctl reload httpd.service</code></tvar>. These commands need to be run as root, usually by prefixing them with <tvar name=sudo><code>sudo ...</code></tvar>.</translate>

<translate>
=== Where to put <tvar name=hta>.htaccess</tvar> === <!--T:24-->
</translate>

{{note|1=<translate><!--T:25--> On Apache the <tvar name=code1><code>AllowOverride</code></tvar> controls whether .htaccess files are allowed to control server configuration. If these rewrite rules do nothing at all you may have to modify the <tvar name=code2><code>AllowOverride</code></tvar> setting in the Apache config to include <tvar name=code3><code>FileInfo</code></tvar>. It also requires <tvar name=code4><code>Options FollowSymLinks</code></tvar> for the directory.</translate>}}

<translate>
<!--T:26-->
If you're using a <tvar name=htaccess><code>.htaccess</code></tvar> file you'll need to edit or create the file. Find the path that contains both your script path and your virtual path. Usually this means the top directory of your site, but let's look at a few examples:
</translate>

{| class="wikitable"
! {{ll|Manual:$wgScript|wgScript}}
! <translate><!--T:79--> Example</translate>
! {{ll|Manual:$wgArticlePath|wgArticlePath}}
! <translate><!--T:80--> Example</translate>
! <translate><!--T:103--> .htaccess location</translate>
|-
| /w/index.php
|<nowiki>https://www.mediawiki.org/w/index.php?</nowiki>...
| /wiki/Page_title
|<nowiki>https://www.mediawiki.org/wiki/Manual:Short_URL</nowiki>
| /.htaccess
|-
| /w/index.php
|<nowiki>https://www.mediawiki.org/w/index.php?</nowiki>...
| /Page_title
|<nowiki>https://www.mediawiki.org/Manual:Short_URL</nowiki>
| /.htaccess
|-
| /mediawiki/index.php
|<nowiki>https://www.mediawiki.org/mediawiki/index.php?</nowiki>...
| /view/Article
|<nowiki>https://www.mediawiki.org/view/Manual:Short_URL</nowiki>
| /.htaccess
|-
| /mysite/mw/index.php
|<nowiki>https://www.mediawiki.org/mysite/mw/index.php?</nowiki>...
| /mysite/view/Page_title
|<nowiki>https://www.mediawiki.org/mysite/view/Manual:Short_URL</nowiki>
| /mysite/.htaccess
|}

<translate>
<!--T:27-->
Note that if you want to make a redirect from the main domain to your wiki's Main Page (e.g. <tvar name=code><nowiki>http://example.org/</nowiki> {{pa|next}} <nowiki>http://example.org/wiki/Main_Page</nowiki></tvar>). Then you always have to set up the .htaccess file in the top level, even if the other directories are nested deeper.

=== Setting up the rewrite rules === <!--T:28-->

<!--T:29-->
It's easier to understand the rest of this section after a glimpse at the Apache syntax, but this synopsis is not a substitute for the full Apache documentation:
</translate>

<syntaxhighlight lang="apache">
RewriteCond TestString CondPattern
RewriteRule Pattern Substitution [flags]
</syntaxhighlight>

<translate><!--T:30--> The <tvar name=1><code>RewriteCond</code></tvar> directive defines a condition that must be true before a RewriteRule that follows it may be applied.</translate>
<translate><!--T:92--> One or more RewriteCond directives may precede a RewriteRule directive, and all the RewriteCond directives that precede a RewriteRule must be true before that rule may be applied to a URI.</translate>
<translate><!--T:93--> In the examples that follow, <tvar name=1><code>TestString</code></tvar> takes the form of a reference to server variables, e.g. <tvar name=2><code>%{ NAME_OF_VARIABLE }</code></tvar>.</translate>
<translate><!--T:94--> Although many <tvar name=1><code>CondPatterns</code></tvar> exist, the examples that follow use <tvar name=2><code>-f</code></tvar> (true when TestString is a regular file) and <tvar name=3><code>-d</code></tvar> (true when TestString is a directory), and they are preceded by a negation symbol, <tvar name=4><code>!</code></tvar>.</translate>

<translate>
<!--T:31-->
The <tvar name=RewriteRule><code>RewriteRule</code></tvar> directive may be invoked in both the <tvar name=httpd><code>httpd.conf</code></tvar> file and in any <tvar name=hta1><code>.htaccess</code></tvar> file, but when the rewrite rule appears in .htaccess files, the implicit per-directory context affects the rule's <code>Pattern</code> because rules are relative to the current directory.  In <tvar name=hta2><code>.htaccess</code></tvar> files, Patterns are ''not'' relative to the complete, original URI.  For <tvar name=hta3><code>.htaccess</code></tvar> files, Patterns should never start with a forward slash, <tvar name=slash1><code>/</code></tvar>, because the URI sub-string will never begin with a <tvar name=slash2><code>/</code></tvar>.  The examples that follow use the <tvar name=l><code>L</code></tvar> flag whose meaning is ''Stop the rewriting process immediately, and don't apply any more rules''.
</translate><br />


{{note|1=<translate><!--T:32--> The <tvar name=mod><code>mod_rewrite</code></tvar> module must be enabled in Apache or LiteSpeed servers for the examples that follow.</translate>}}

{{note|1=<translate><!--T:33--> If you are using VirtualHosts, be sure that settings are placed inside the VirtualHost declaration</translate>}}

<translate>
<!--T:34-->
The first rule you'll need inside of your config is one to enable the rewrite engine:
</translate>

<syntaxhighlight lang="apache">
RewriteEngine On
</syntaxhighlight>

<translate>
<!--T:35-->
Now we need a rule to make your article path a virtual path pointing to index.php. Be sure to replace <tvar name=wiki><code>/wiki</code></tvar> and <tvar name=index><code>/w/index.php</code></tvar> with the paths you [[<tvar name=plan>#Plan</tvar>|chose in the beginning]] (if different).
</translate>

<syntaxhighlight lang="apache">
RewriteRule ^/?wiki(/.*)?$ %{DOCUMENT_ROOT}/w/index.php [L]
</syntaxhighlight>

{{note|1=<translate><!--T:36--> If you decide to customize this, be sure to '''never''' include <tvar name=code><code>?title=$1</code></tvar> or something like it in the rewrite. Including a query will cause MediaWiki's built in  handling to be overridden and will create bugs on your wiki due to the fact that Apache's query rewrites are broken.</translate><ref>[http://dracos.co.uk/code/apache-rewrite-problem/ <translate><!--T:52--> The Apache mod_rewrite Problem</translate>]</ref> <translate><!--T:53--> The goal here is to alias paths to /index.php and then let MediaWiki itself take care of parsing and routing the url, based on the configuration in <tvar name=ls>[[#LocalSettings.php|LocalSettings.php]]</tvar>.</translate>}}

<translate>
<!--T:37-->
If you are using a root url instead of a normal short url you will need to use the following instead (to ensure that existing files and directories are not seen as article, e.g. "<tvar name=index><code>/index.php</code></tvar>" "<tvar name=images><code>/images</code></tvar>" etc.):
</translate>

<syntaxhighlight lang="apache">
RewriteCond %{REQUEST_URI} !^/w/rest\.php
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} !-f
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} !-d
RewriteRule ^(.*)$ %{DOCUMENT_ROOT}/w/index.php [L]
</syntaxhighlight>

{{note|1=<translate><!--T:38--> If you are using a script path and article path that match such as <tvar name=myw-index><code>/mywiki/index.php</code></tvar> and <tvar name=article1><code>/mywiki/Article</code></tvar> you will also need to use the same two RewriteCond lines on your RewriteRule. However please note that there is no real valid reason to configure your wiki this way. If your article path is already a subdirectory you should just move your wiki's script path to another directory. Such as <tvar name=w-index><code>/w/index.php</code></tvar> and <tvar name=article2><code>/mywiki/Article</code></tvar> or <tvar name=my-index><code>/my/index.php</code></tvar> and <tvar name=artticle3><code>/mywiki/Article</code></tvar>.</translate>}}

<translate>
<!--T:39-->
Sometimes, the above example doesn't work. The following (you can't set this in a <tvar name=hta><code>.htaccess</code></tvar>, you need root access for this!) might work instead:
</translate>

<syntaxhighlight lang="apache">
Alias /wiki /path/to/your/webroot/w/index.php
</syntaxhighlight>

<translate><!--T:40-->
Optionally, you can include a rule to show the Main Page on the path itself, to simplify navigation when people visit urls without a page title specified:
</translate>

<syntaxhighlight lang="apache">
# <translate nowrap><!--T:55--> Redirect / to Main Page</translate>
RewriteRule ^/*$ %{DOCUMENT_ROOT}/w/index.php [L]
</syntaxhighlight>

<translate><!--T:41-->
The end result should look something like this:
</translate>

<syntaxhighlight lang="apache">
## https://www.mediawiki.org/wiki/Manual:Short_URL/Apache

# <translate nowrap><!--T:56--> Enable the rewrite engine</translate>
RewriteEngine On

# <translate nowrap><!--T:57--> Short URL for wiki pages</translate>
RewriteRule ^/?wiki(/.*)?$ %{DOCUMENT_ROOT}/w/index.php [L]

# <translate nowrap><!--T:58--> Redirect / to Main Page</translate>
RewriteRule ^/*$ %{DOCUMENT_ROOT}/w/index.php [L]
</syntaxhighlight>

<translate><!--T:104--> or, if you used the way with the "Alias" statement:</translate>

<syntaxhighlight lang="apache">
## https://www.mediawiki.org/wiki/Manual:Short_URL/Apache

Alias /wiki /path/to/your/webroot/w/index.php
# <translate nowrap><!--T:59--> Enable the rewrite engine</translate>
RewriteEngine On

# <translate nowrap><!--T:60--> Redirect / to Main Page</translate>
RewriteRule ^/*$ %{DOCUMENT_ROOT}/w/index.php [L]
</syntaxhighlight>

{{note|1=<translate><!--T:42--> Make sure that the order of rules as given in the example is being preserved, i.e. "Short url for wiki pages" must be checked prior to "Redirect / to Main Page".</translate>}}

{{note|1=<translate><!--T:43--> The <tvar name=code1><code>^/?</code></tvar> in the config is important because different Apache setups use different regexps. Some want you to use <tvar name=code2><code>^wiki/</code></tvar> and some want you to use <tvar name=code3><code>^/wiki/</code></tvar>. The <tvar name=code4><code>?</code></tvar> in <tvar name=code5><code>/?</code></tvar> allows this rule to work in both contexts.</translate>}}

{{note|1=<translate><!--T:44--> The <tvar name=code1><code>%{DOCUMENT_ROOT}</code></tvar> in the config ensures that Apache has the correct non-ambiguous path. However it does not work on some badly configured free hosts. If you have 404 or 403 issues with your RewriteRules, remove the <tvar name=code2><code>%{DOCUMENT_ROOT}</code></tvar> parts and try again.</translate>}}

{{note|1=<translate><!--T:45--> If your SCRIPT_PATH leads to some other physical location (known as "symlink" in Unix, "shortcut" on Windows, "alias" in Mac OS X), you may need to allow Apache to follow those. You can do so by adding this line above the <tvar name=RewriteEngine><code>RewriteEngine</code></tvar>:</translate><br/><code>Options +FollowSymLinks</code>}}

{{note|1=<translate><!--T:46--> If the path to your script directory is aliased by the webserver via an Alias directive, as it is in Debian among others, the RewriteRule will work as long as you add the PT flag (ie: change <tvar name=l><code>[L]</code></tvar> to <tvar name=ptl><code>[PT,L]</code></tvar>)  to Pass Through the request to the next handler - mod_alias, which will correctly redirect the request, as per [<tvar name=stackoverflow>http://stackoverflow.com/questions/334111/how-to-use-apache-mod-rewrite-and-alias-at-the-same-time</tvar> Stack Overflow]</translate>}}

== LocalSettings.php ==
<translate>
<!--T:48-->
We need to make the following configurations in <tvar name=ls>{{Manual|LocalSettings.php}}</tvar>:
</translate>

<syntaxhighlight lang="php">
## https://www.mediawiki.org/wiki/Manual:Short_URL
$wgScriptPath = "/w";        // <translate nowrap><!--T:61--> this should already have been configured this way</translate>
$wgArticlePath = "/wiki/$1";
</syntaxhighlight>

<translate>
<!--T:49-->
If you get an "Internal error" page saying "Redirect loop detected!" after you finish configuration you may be using something other than <tvar name=1><code>mod_php</code></tvar>. If so you need to explicitly turn on short urls using the following line in your "<tvar name=2>LocalSettings.php</tvar>" file:
</translate>

<syntaxhighlight lang="php">
$wgUsePathInfo = true;
</syntaxhighlight>

<translate>
<!--T:54-->
If there is still an "internal error" check the log files of your server. Maybe you have to turn on <tvar name=code><code>mod_rewrite</code></tvar> module.

==Simple instructions== <!--T:81-->
</translate>
<translate><!--T:82--> The following is a summary of what to do if you are not doing anything different than what MediaWiki recommends.</translate>
<translate><!--T:83--> If you want to do something else, you need to read all of the details above.</translate>

* https://example.com/wiki/Main_Page (<translate><!--T:84--> url location</translate>)
* /home/me/public_html/mediawiki/w/index.html (<translate><!--T:85--> <tvar name=1>index.html</tvar> location</translate>)
* /home/me/public_html/mediawiki/.htaccess (<translate><!--T:86--> <tvar name=1>.htaccess</tvar> location</translate>)

<translate>
<!--T:87-->
Notice that the <tvar name=1>.htaccess</tvar> file is NOT located in the "<tvar name=2>w</tvar>" directory, but it is located in the directory above it.

===<tvar name=1>.htaccess</tvar> source code=== <!--T:88-->
</translate>
<syntaxhighlight lang="apache">
RewriteEngine On

# <translate nowrap><!--T:95--> main rewrite rule</translate>
RewriteRule ^/?wiki(/.*)?$ %{DOCUMENT_ROOT}/w/index.php [L]

# <translate nowrap><!--T:96--> Redirect / to Main Page</translate>
RewriteRule ^/*$ %{DOCUMENT_ROOT}/w/index.php [L]
</syntaxhighlight>

<translate>
===<tvar name=1>LocalSettings.php</tvar> source code=== <!--T:89-->
</translate>
<syntaxhighlight lang="php">
$wgScriptPath = "/w";
$wgArticlePath = "/wiki/$1";
</syntaxhighlight>

<translate>
== Online Wizard == <!--T:97-->
</translate>
<translate><!--T:98--> It is possible that this wizard will help people generate the short URLs they need.</translate>
<translate><!--T:105--> (NOTE: This needs to be tested, or the section removed.)</translate>

<translate><!--T:106--> An automated wizard (requires MediaWiki 1.17 or later) might help:</translate>

* '''[https://shorturls.redwerks.org/ shorturls.redwerks.org]''' 

<translate><!--T:107--> If you just want your wiki configured quickly or you find the guide confusing then you may want to try that tool first.</translate>
<translate><!--T:99--> If you do this, please note that you will need to edit or create a <tvar name=1>.htaccess</tvar> file.</translate>
<translate><!--T:100--> If you create it anew, please read on to further in this article about [[<tvar name=1>Special:MyLanguage/Manual:Short URL/Apache#Where to put .htaccess</tvar>|where to place the <tvar name=2>.htaccess</tvar> file]], and please note that this file will likely be in a different folder than the other file that will need to be edited (<tvar name=3>LocalSettings.php</tvar>), which is in the installation folder (<tvar name=4>/w</tvar> if you have followed the MediaWiki recommendations).</translate>
<translate><!--T:108--> Please also note that using this wizard will not work on firewalled or private wikis.</translate>
<translate><!--T:101--> In this case, you can still try it out by making your wiki temporarily public by setting <tvar name=1><code>$wgGroupPermissions['*']['read']</code></tvar> to <tvar name=2>{{phpi|true}}</tvar>.</translate>
<translate><!--T:102--> Remember to change it back to <tvar name=1>{{phpi|false}}</tvar> once you are done.</translate>

<translate>
== See also == <!--T:50-->
</translate>
* {{wg|ScriptPath}}
* {{wg|ArticlePath}}
* {{wg|ActionPaths}}

<translate>
== References == <!--T:51-->
</translate>


<references/>

[[Category:Wiki page URLs{{#translation:}}]]