Difference between pages "Ebuild Functions" and "MediaWiki"

From Funtoo
(Difference between pages)
Jump to: navigation, search
 
 
Line 1: Line 1:
== Ebuild Functions ==
+
This page documents how to set up MediaWiki on Funtoo Linux, from a bare stage3 install with network connectivity. We will use Nginx, xcache and PHP-FPM, which will result in very good performance. We will also properly secure MediaWiki, and also cover some additional tips and tricks, focusing on spam reduction.
  
Ebuilds provide the ability to define various shell functions that are used to specify various actions relating to building and installing a source or binary package on a user's system. When an ebuild is emerged, the following functions are called, in order:
+
== Portage Settings ==
  
* <tt>pkg_setup</tt> - variable intialization and sanity checks
+
Add the following line to <tt>/etc/make.conf</tt>:
* <tt>src_unpack</tt>
+
* <tt>src_prepare</tt>
+
* <tt>src_configure</tt>
+
* <tt>src_compile</tt>
+
* <tt>src_install</tt>
+
  
At this point, the files are ready to be "merged" into the live filesystem. This is when they are copied from the temporary build directory into <tt>/usr</tt>, etc. At this point, the following functions are executed:
 
  
* <tt>pkg_preinst</tt>
+
<pre>
* (files are merged)
+
PHP_TARGETS="php5-4"
* <tt>pkg_postinst</tt>
+
</pre>
  
=== src_* functions ===
+
Add the following lines to <tt>/etc/portage/package.use/php</tt>:
  
Ebuild functions starting with <tt>src_</tt> are all related to creating the ebuild or package from source code/artifacts, and are defined below:
+
<pre>
 +
dev-lang/php curl exif fpm gd mysql mysqli sockets suhosin threads intl xmlreader xmlwriter
 +
>=dev-php/xcache-2.0.0 php_targets_php5-4
 +
</pre>
  
==== src_unpack ====
+
== Emerge ==
  
<tt>src_unpack</tt> is intended to be used to unpack the source code/artifacts that will be used by the other <tt>src_*</tt> functions. With EAPI 1 and earlier, it is also used for patching/modifying the source artifacts to prepare them for building, but with EAPI 2 or later the <tt>src_prepare</tt> function should be used for this instead. When <tt>src_unpack</tt> starts, the current working directory is set to <tt>$WORKDIR</tt>, which is the directory within which all source code/artifacts should be expanded. Note that the variable <tt>$A</tt> is set to the names of all the unique source files/artifacts specified in <tt>SRC_URI</tt>, and they will all be available in <tt>$DISTDIR</tt> by the time <tt>src_unpack</tt> starts. Also note that if no <tt>src_unpack</tt> function is specified, <tt>ebuild.sh</tt> will execute the following function for <tt>src_unpack</tt> by default:
+
Emerge xcache, and we'll also emerge metalog and postfix. This should pull in MySQL as well as php-5.4:
  
<pre>
+
<console>
src_unpack() {
+
# ##i##emerge --jobs xcache metalog postfix
  unpack ${A}
+
</console>
}
+
</pre>
+
  
==== src_prepare ====
+
== Start and Configure Services ==
  
EAPI 2 and above support the <tt>src_prepare</tt> function, which is intended to be used for applying patches or making other modifications to the source code. When <tt>src_prepare</tt> starts, the current working directory is set to <tt>$S</tt>.
+
Time to configure MySQL with a root password, start it, secure it, and enable it to start at boot. We'll also start metalog and postfix:
  
==== src_configure ====
+
<console>
 +
# ##i##emerge --config mysql
 +
# ##i##rc-update add mysql default
 +
# ##i##rc-update add metalog default
 +
# ##i##rc-update add postfix default
 +
# ##i##rc
 +
# ##i##mysql_secure_installation
 +
</console>
  
EAPI 2 and above support the <tt>src_configure</tt> function, which is used to configure the source code prior to compilation. With EAPI 2 and above, the following default <tt>src_configure</tt> is defined if none is specified:
+
== Database Setup ==
 +
 
 +
Now, let's create a database named <tt>mediawiki</tt> for use by MediaWiki, and a <tt>mediawiki@localhost</tt> user to access this database, using a password of <tt>wikifever</tt>:
 +
 
 +
<console>
 +
# ##i##mysql -u root -p
 +
Enter password:
 +
Welcome to the MySQL monitor.  Commands end with ; or \g.
 +
Your MySQL connection id is 7
 +
Server version: 5.1.62-log Gentoo Linux mysql-5.1.62-r1
 +
 
 +
Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved.
 +
 
 +
Oracle is a registered trademark of Oracle Corporation and/or its
 +
affiliates. Other names may be trademarks of their respective
 +
owners.
 +
 
 +
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
 +
 
 +
mysql> ##i##create database mediawiki;
 +
Query OK, 1 row affected (0.01 sec)
 +
 
 +
mysql> ##i##grant index, create, select, insert, update, delete, alter, lock tables on mediawiki.* to 'mediawiki'@'localhost' identified by 'wikifever';
 +
Query OK, 0 rows affected (0.01 sec)
 +
 
 +
mysql> ##i##\q
 +
Bye
 +
#
 +
</console>
 +
 
 +
== Nginx Setup ==
 +
 
 +
We will use nginx as our Web server. Let's emerge it:
 +
 
 +
<console>
 +
# ##i##emerge --jobs nginx
 +
</console>
 +
 
 +
== User and Group ==
 +
 
 +
When we run our wiki, we will run it as the <tt>docs</tt> user, for security. Let's set up a <tt>docs</tt> user and group:
 +
 
 +
<console>
 +
# ##i##groupadd docs
 +
# ##i##useradd -g docs --home /home/docs docs
 +
# ##i##install -d /home/docs
 +
# ##i##chown -R docs:docs /home/docs
 +
</console>
 +
 
 +
== Set up PHP ==
 +
 
 +
As our last major configuration step, we will configure the PHP FastCGI Process Manager by creating a <tt>/etc/php/fpm-php5.4/php-fpm.conf</tt> file with the following contents (existing contents can be deleted):
  
 
<pre>
 
<pre>
src_configure() {
+
[global]
if [[ -x ${ECONF_SOURCE:-.}/configure ]] ; then
+
error_log = /var/log/php-fpm.log
econf
+
log_level = notice
fi
+
 
}
+
[docs]
 +
listen = /var/run/docs.php-fpm.socket
 +
listen.allowed_clients = 127.0.0.1
 +
listen.owner = docs
 +
listen.group = nginx
 +
listen.mode = 0660
 +
user = docs
 +
group = docs
 +
pm = dynamic
 +
pm.max_children = 16
 +
pm.start_servers = 2
 +
pm.min_spare_servers = 2
 +
pm.max_spare_servers = 2
 +
pm.max_requests = 500
 +
php_admin_value[open_basedir] = /home/docs/public_html:/tmp
 +
php_admin_value[error_log] = /home/docs/php-errors.log
 +
php_admin_value[disable_functions] = exec, system, shell_exec, passthru, popen, dl, curl_multi_exec, posix_getpwuid,
 +
disk_total_space, disk_free_space, escapeshellcmd, escapeshellarg, eval, get_current_user, getmyuid, getmygid,
 +
posix_getgrgid, parse_ini_file, proc_get-status, proc_nice, proc_terminate, suexec, pclose, virtual, set_time_limit, show_source
 
</pre>
 
</pre>
  
==== src_compile ====
+
This configuration file tells PHP to use the <tt>docs</tt> user when running MediaWiki. '''Please note that the last line is very long - I have split it into 3 lines for readability on this wiki, but you should combine them into a single line in your configuration file. The line should start with <tt>php_admin_value[disable_functions]</tt> and end with <tt>show_source</tt>.
  
This function defines the steps necessary to compile source code. With EAPI 1 and earlier, this function is also used to configure the source code prior to compilation. However, starting with EAPI 2, the <tt>src_configure</tt> function must be used for configuration steps instead of bundling them inside <tt>src_compile</tt>. In addition, starting with EAPI 2, there is now a default <tt>src_compile</tt> function that will be executed if none is defined in the ebuild:
+
== Configure Nginx ==
 +
 
 +
Oh! Now we need to configure nginx to serve pages as the docs user. Assuming your site is named wiki.mysite.com, create a <tt>/etc/nginx/sites-available/wiki.mysite.com</tt> file with the following contents:
  
 
<pre>
 
<pre>
src_compile() {
+
server {
if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ] ; then
+
        listen 80;
emake || die "emake failed"
+
        server_name wiki.mysite.com;
fi
+
 
 +
        access_log /var/log/nginx/wiki.mysite.com.access.log main;
 +
        error_log /var/log/nginx/wiki.mysite.com.error.log error;
 +
       
 +
        root /home/docs/public_html;
 +
        index index.html index.php;
 +
 
 +
        # uncomment this if you want to htpasswd-protect your site while you set it up initially
 +
        # auth_basic "Ninjas allowed only";
 +
        # auth_basic_user_file /etc/nginx/docs.funtoo.org.htpasswd;
 +
 
 +
location ~* ^(.*)(install.php|LocalSettings.php|\.git) { deny all; }
 +
 
 +
location ~* \.php$ {
 +
        #set $https "off";
 +
        #if ($scheme = https) { set $https "on"; }
 +
        #fastcgi_param HTTPS $https;
 +
 
 +
        try_files      $uri    @404;
 +
        fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
 +
        fastcgi_param  SERVER_SOFTWARE    nginx;
 +
        fastcgi_param  QUERY_STRING      $query_string;
 +
        fastcgi_param  REQUEST_METHOD    $request_method;
 +
        fastcgi_param  CONTENT_TYPE      $content_type;
 +
        fastcgi_param  CONTENT_LENGTH    $content_length;
 +
        fastcgi_param  SCRIPT_FILENAME    $document_root$fastcgi_script_name;
 +
        fastcgi_param  SCRIPT_NAME        $fastcgi_script_name;
 +
        fastcgi_param  REQUEST_URI        $request_uri;
 +
        fastcgi_param  DOCUMENT_URI      $document_uri;
 +
        fastcgi_param  DOCUMENT_ROOT      $document_root;
 +
        fastcgi_param  SERVER_PROTOCOL    $server_protocol;
 +
        fastcgi_param  REMOTE_ADDR        $remote_addr;
 +
        fastcgi_param  REMOTE_PORT        $remote_port;
 +
        fastcgi_param  SERVER_ADDR        $server_addr;
 +
        fastcgi_param  SERVER_PORT        $server_port;
 +
        fastcgi_param  SERVER_NAME        wiki.mysite.com;
 +
 
 +
        fastcgi_pass    unix:/var/run/docs.php-fpm.socket;
 +
        fastcgi_index  index.php;
 
}
 
}
</pre>
 
  
==== src_test ====
+
# this will secure the MediaWiki uploads against arbitrary PHP injection attacks:
 +
location /images/ {
 +
        location ~.*\.(php)?$ {
 +
                deny all;
 +
        }
 +
}
  
<tt>src_test</tt> is an interesting function - by default, an end-user's Portage does not have tests enabled. But if a user has <tt>test</tt> in <tt>FEATURES</tt>, or <tt>EBUILD_FORCE_TEST</tt> is defined, then <tt>ebuild.sh</tt> will attempt to run a test suite for this ebuild, by executing <tt>make check</tt> or <tt>make test</tt> if these targets are defined in the Makefile; otherwise, no tests will execute. If your Makefile supports <tt>make check</tt> or <tt>make test</tt> but the test suite is broken, then specify <tt>RESTRICT="test"</tt> in your ebuild to disable the test suite.
 
  
==== src_install ====
+
location @404 {
 +
        return 404;
 +
        break;
 +
}
  
<tt>src_install</tt> is used by the ebuild writer to install all to-be-installed files to the <tt>$D</tt> directory, which can be treated like an empty root filesystem, in that <tt>${D}/usr</tt> is the equivalent of the <tt>/usr</tt> directory, etc. When <tt>src_install</tt> runs, the Portage sandbox will be enabled, which will prevent any processes from creating or modifying files outside of the <tt>${D}</tt> filesystem tree, and a sandbox violation will occur (resulting in the termination of the ebuild) if any such sandbox violation should occur. Once <tt>src_install</tt> has perfomed all necessary steps to install all to-be-installed files to <tt>$D</tt>, Portage will take care of merging these files to the filesystem specified by the <tt>$ROOT</tt> environment variable, which defaults to <tt>/</tt> if not set. When Portage merges these files, it will also record information about the installed package to <tt>/var/db/pkg/(cat)/$P</tt>. Typically, a <tt>src_install</tt> function such as this is sufficient for ensuring that all to-be-installed files are installed to <tt>$D</tt>:
+
location / {
 +
        try_files $uri $uri/ @mediawiki;
 +
}
 +
 
 +
location @mediawiki {
 +
        rewrite ^/([^?]*)(?:\?(.*))? /index.php?title=$1&$2 last;
 +
}
  
<pre>
 
src_install() {
 
  make DESTDIR="$D" install
 
 
}
 
}
 
</pre>
 
</pre>
  
=== pkg_* functions ===
+
== Enable Ngnix and PHP-FPM ==
  
An ebuild's functions starting with <tt>pkg_*</tt> take a wider view of the package lifecycle, and may be executed very early or very late in the build or package installation process. They are also all executed even if installing a Portage binary package, so are the intended place for defining any global configuration changes that are also required during binary package installation, such as user and group creation. When these functions are executed, the <tt>$ROOT</tt> variable will be defined to point to the target root filesystem to which the package is to be (or has been) installed. All logic inside <tt>pkg_*</tt> functions must function properly even if <tt>$ROOT</tt> is something other than <tt>/</tt>.
+
Now, let's enable nginx to serve our site, and also be sure to enable php-fpm:
  
==== pkg_setup ====
+
<console>
 +
# ##i##cd /etc/nginx/sites-enabled
 +
# ##i##ln -s ../sites-available/wiki.mysite.com wiki.mysite.com
 +
# ##i##rc-update add nginx default
 +
# ##i##rc-update add php-fpm default
 +
# ##i##rc
 +
* Starting PHP FastCGI Process Manager ...                                                            [ ok ]
 +
* Starting nginx ...                                                                                  [ ok ]
 +
#
 +
</console>
  
The <tt>pkg_setup</tt> function is unusual in that it runs prior to any <tt>src_*</tt> function, and also runs prior to any other <tt>pkg_*</tt> function that runs when a binary package is installed, so it provides a useful place for the ebuild writer to perform any sanity checks, global configuration changes to the system (such as user/group creation) or set any internal global variables that are used by the rest of the ebuild. Using this function for defining global variables that are needed in multiple other functions is a useful way of avoiding duplicate code. You should also look to <tt>pkg_setup</tt> as the ideal place to put any logic that would otherwise linger in the main body of the ebuild, which should be avoided at all costs as it will slow down dependency calculation by Portage. Also remember that Portage can build binary packages, and this function is a good place to execute any steps that are required to run both prior to building an ebuild, and prior to installing a package. Also consider using <tt>pkg_preinst</tt> and <tt>pkg_postinst</tt> for this purpose.
+
== Download MediaWiki ==
  
==== pkg_pretend ====
+
We're getting close. Now, head to http://www.mediawiki.org/wiki/Download and copy the link address for the latest version of MediaWiki, currently 1.19.1 at the time this was written. Let's download the archive to <tt>/var/tmp</tt>:
  
The <tt>pkg_pretend</tt> function was added with EAPI 3, and it's the opinion of Daniel Robbins that the use of this function should be avoided. This function is especially unusual in that it is intended to be run ''during dependency calculation'', and is intended to provide a polite mechanism to inform the user that a particular ebuild will fail due to a known incompatibility, typically a kernel incompatibility. That way, the user can know during <tt>emerge --pretend</tt> that a merge will fail. While this is useful, extending the dependency engine using <tt>bash</tt> is a very low-performance means to perform these tests. Therefore, The Funtoo core team recommends against using <tt>pkg_pretend</tt>. An extensible dependency engine would be a more appropriate and high-performance way to provide identical functionality.
+
<console>
 +
# ##i##cd /var/tmp
 +
# ##i##wget http://download.wikimedia.org/mediawiki/1.19/mediawiki-1.19.1.tar.gz
 +
</console>
  
==== pkg_preinst ====
+
== Extract MediaWiki ==
  
The <tt>pkg_preinst</tt> function is called by Portage, prior to merging the to-be-installed files to the target filesystem specified by <tt>$ROOT</tt> environment variable (which defaults to <tt>/</tt>.) Keep in mind that these to-be-installed files were either just compiled and installed to <tt>$D</tt> by <tt>src_install</tt>, or they were just extracted from a <tt>.tbz2</tt> binary package. The <tt>pkg_preinst</tt> function provides an ideal place to perform any "just before install" actions, such as user and group creation or other necessary steps to ensure that the package merges successfully. It also provides a potential place to perform any sanity checks related to installing the package to the target filesystem. If any sanity checks fail, calling <tt>die</tt> from this function will cause the package to not be installed to the target filesystem.
+
We now have all the Web, database and email infrastructure enabled that we need. Heading to the IP address of your server should result in a 404 - Not Found error in your Web browser. Time to extract and configure MediaWiki itself:
  
==== pkg_postinst ====
+
<console>
 +
# ##i##su docs
 +
$ ##i##cd /var/tmp
 +
$ ##i##tar xvf ./mediawiki-1.19.1.tar.gz
 +
$ ##i##mv mediawiki-1.19.1 ~/public_html
 +
</console>
  
The <tt>pkg_postinst</tt> function is called by Portage prior to the package being installed to the target filesystem specified by <tt>$ROOT</tt>. This is a good place to perform any post-install configuration actions as well as print any informational messages for the user's benefit related to the package that was just installed.
+
== MediaWiki from GIT ==
  
==== pkg_prerm ====
+
Alternatively, we can download the code from the git repository:
  
The <tt>pkg_prerm</tt> function is called by Portage before an ebuild is removed from the filesystem.
+
<console>
 +
# ##i##su docs
 +
$ ##i##cd ~
 +
$ ##i##git clone https://gerrit.wikimedia.org/r/p/mediawiki/core.git public_html
 +
</console>
  
==== pkg_postrm ====
+
Specific stable versions of MediaWiki are tracked using 'tags'. These are analogous to the tarball releases. We can see the versions available with:
 +
<console>
 +
$ ##i##cd public_html
 +
$ ##i##git tag -l | sort -V
 +
</console>
  
The <tt>pkg_postrm</tt> function is called by Portage after an ebuild is removed from the filesystem.
+
To use a specific tag (1.19.1):
 +
<console>
 +
$ ##i##git checkout 1.19.1
 +
</console>
  
==== pkg_config ====
+
== Initial Web Config ==
  
The <tt>pkg_config</tt> function is called by Portage when the user calls <tt>emerge --config</tt> for the ebuild. The current directory will be set to the current directory of the shell from where <tt>emerge --config</tt> is run.
+
You will now be able to load the URL of your server in your Web browser and configure MediaWiki through the Web user interface. Complete the '''full''' installation process and be sure to specify that you are using XCache for caching. Once you go through this process, the Web installation process will provide you with a <tt>LocalSettings.php</tt> file, which you should place in <tt>/home/docs/public_html</tt>. The <tt>LocalSettings.php</tt> file can also be manually edited and used to enable MediaWiki features and extensions.
  
=== Extra pre_ and post_ functions ===
+
== Tips and Tricks ==
  
Modern versions of Portage also support functions identical to the above functions but with '''pre_''' and '''post_''' at the beginning of the function name. For example, <tt>post_src_configure</tt> will be executed after <tt>src_configure</tt> and before <tt>src_compile</tt>. These additional functions are supported by all EAPIs, provided that the parent function is supported by the EAPI in use. The initial current working directory should be identical to the initial current working directory of the parent function.
+
=== ArticlePath ===
  
=== Helper Functions ===
+
By default, MediaWiki pages will have a URL of <tt>wiki.myserver.com/index.php?title=PageName</tt>. With a few minor tweaks, you can tell MediaWiki to use <tt>wiki.myserver.com/PageName</tt> instead. Here's how. Open up <tt>LocalSettings.php</tt> and search for the <tt>$wgScriptPath</tt> line. This part of the config will look like this:
  
==== econf() ====
+
<pre>
 +
$wgScriptPath      = "";
 +
$wgScriptExtension  = ".php";
 +
</pre>
  
econf() is part of ebuild.sh and is intended to be a wrapper to the <tt>configure</tt> command that is typically used in the <tt>src_configure()</tt> stage. It has a number of behaviors that are important for ebuild writers to understand. Once you understand what <tt>econf()</tt> does, you are free to use it in your ebuilds. Note that the behavior of <tt>econf()</tt> is generally safe for most autoconf-based source archives, but in some cases it may be necessary to avoid using <tt>econf()</tt> to avoid some of its default behaviors.
+
Change this part of the file to look like this:
  
===== Automatically set prefix =====
+
<pre>
 +
$wgScriptPath      = "";
 +
$wgArticlePath      = "/$1";
 +
$wgUsePathInfo      = true;
 +
$wgScriptExtension  = ".php";
 +
</pre>
  
<tt>--prefix=/usr</tt> will be passed to <tt>configure</tt> automatically, unless a <tt>--prefix</tt> argument was specified to <tt>econf()</tt>, in which case, that <tt>--prefix</tt> setting will be used instead.
+
The old-style URLs will still work, but the shorter more intuitive URLs will now be used for all wiki links.
  
===== Automatically set libdir =====
+
=== $wgSpamRegex ===
  
If the <tt>ABI</tt> variable is set (typically done in the profile), then <tt>econf()</tt> will look for a variable named <tt>LIBDIR_$ABI</tt> (ie. <tt>LIBDIR_amd64</tt>). If this variable is set, the value of this variable will be used to set <tt>libdir</tt> to the value of <tt>{prefix}/LIBDIR_$ABI</tt>.
+
You may find that your wiki is the target of spammers. The easiest way to combat spam is to set <tt>$wgSpamRegex</tt> in <tt>LocalSettings.php</tt>, like so:
  
===== Automatically set CHOST and CTARGET =====
+
<pre>
 +
$wgSpamRegex = "/badword1|badword2|badword3/i"
 +
</pre>
  
The <tt>--host=$CHOST</tt> argument will be passed to <tt>configure</tt>. <tt>$CHOST</tt> is defined in the system profile. In addition, the <tt>--target=$CTARGET</tt> argument will be passed to <tt>configure</tt> if <tt>$CTARGET</tt> is defined. This is not normally required but is done to make Portage more capable of cross-compiling the ebuild. However, this functionality is not a guarantee that your ebuild will successfully cross-compile, as other changes to the ebuild may be necessary.
+
This will perform a case-insensitive match against the bad words and block anyone from saving edits that contain these words.
  
===== Disable Dependency Tracking (EAPI 4) =====
+
=== DNS Blacklist ===
  
In EAPI 4, the <tt>--disable-dependency-tracking</tt> argument will be passed to <tt>configure</tt> in order to optimize the performance of the configuration process. This option should have no impact other than on the performance of the <tt>configure</tt> script.
+
MediaWiki also has the ability to consult a DNS blacklist to prevent known forum and wiki spam sites from performing any edits on your wiki. To enable this capability, add the following to <tt>LocalSettings.php</tt>:
  
===== List of arguments =====
+
<pre>
 +
$wgEnableDnsBlacklist = true;
 +
$wgDnsBlacklistUrls = array( 'xbl.spamhaus.org', 'opm.tornevall.org' );
 +
</pre>
  
The following arguments are passed to <tt>configure</tt> and are all overrideable by the user by passing similar options to <tt>econf()</tt>:
+
You may notice a significant decrease in spam posts.
  
* <tt>--prefix=/usr</tt>
+
=== $wgServer ===
* <tt>--libdir={prefix}/LIBDIR_$ABI</tt>
+
* <tt>--host=${CHOST}</tt>
+
* if CTARGET is defined, then <tt>--target=${CTARGET}</tt>
+
* <tt>--mandir=/usr/share/man</tt>
+
* <tt>--infodir=/usr/share/info</tt>
+
* <tt>--datadir=/usr/share</tt>
+
* <tt>--sysconfdir=/etc</tt>
+
* <tt>--localstatedir=/var/lib</tt>
+
* if EAPI 4+, then <tt>--disable-dependency-tracking</tt>
+
  
[[Category:Internals]]
+
Here is an important tip -- the <tt>$wgServer</tt> variable in <tt>LocalSettings.php</tt> defines the URL of your MediaWiki installation. MediaWiki will encode this within its HTML replies, which means that the Web browser from which you are accessing MediaWiki must be able to reach your server using this address, or pages will not display. This is not a security feature in any way, but a configuration issue. For example, if <tt>$wgServer</tt> is set to <tt>10.0.1.128</tt>, then the only systems that will be able to access your MediaWiki installation are those for which <tt>10.0.1.128</tt> resolves to your MediaWiki installation.  The same is true of non-IP <tt>$wgServer</tt> entries like <tt>wiki.mysite.com</tt>. If you are setting up a test wiki, you may need a temporary entry in a desktop's <tt>/etc/hosts</tt> file so that it can interact with the wiki properly before DNS is set up.
[[Category:Portage]]
+
 
 +
=== $wgLogo ===
 +
 
 +
If you want to change the wiki logo, edit <tt>LocalSettings.php</tt> and replace $wgLogo with the location of the image you want to use:
 +
 
 +
<pre>
 +
$wgLogo = "image.png"
 +
</pre>
 +
{{fancynote| The above references the file <tt>image.png</tt> in the directory <tt>/home/docs/public_html</tt>}}
 +
[[Category:Featured]]
 +
[[Category:HOWTO]]
 
[[Category:Official Documentation]]
 
[[Category:Official Documentation]]

Latest revision as of 23:30, 15 March 2014

This page documents how to set up MediaWiki on Funtoo Linux, from a bare stage3 install with network connectivity. We will use Nginx, xcache and PHP-FPM, which will result in very good performance. We will also properly secure MediaWiki, and also cover some additional tips and tricks, focusing on spam reduction.

Contents

[edit] Portage Settings

Add the following line to /etc/make.conf:


PHP_TARGETS="php5-4"

Add the following lines to /etc/portage/package.use/php:

dev-lang/php curl exif fpm gd mysql mysqli sockets suhosin threads intl xmlreader xmlwriter
>=dev-php/xcache-2.0.0 php_targets_php5-4

[edit] Emerge

Emerge xcache, and we'll also emerge metalog and postfix. This should pull in MySQL as well as php-5.4:

# emerge --jobs xcache metalog postfix

[edit] Start and Configure Services

Time to configure MySQL with a root password, start it, secure it, and enable it to start at boot. We'll also start metalog and postfix:

# emerge --config mysql
# rc-update add mysql default
# rc-update add metalog default
# rc-update add postfix default
# rc
# mysql_secure_installation

[edit] Database Setup

Now, let's create a database named mediawiki for use by MediaWiki, and a mediawiki@localhost user to access this database, using a password of wikifever:

# mysql -u root -p
Enter password: 
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 7
Server version: 5.1.62-log Gentoo Linux mysql-5.1.62-r1

Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql> create database mediawiki;
Query OK, 1 row affected (0.01 sec)

mysql> grant index, create, select, insert, update, delete, alter, lock tables on mediawiki.* to 'mediawiki'@'localhost' identified by 'wikifever';
Query OK, 0 rows affected (0.01 sec)

mysql> \q
Bye
# 

[edit] Nginx Setup

We will use nginx as our Web server. Let's emerge it:

# emerge --jobs nginx

[edit] User and Group

When we run our wiki, we will run it as the docs user, for security. Let's set up a docs user and group:

# groupadd docs
# useradd -g docs --home /home/docs docs
# install -d /home/docs
# chown -R docs:docs /home/docs

[edit] Set up PHP

As our last major configuration step, we will configure the PHP FastCGI Process Manager by creating a /etc/php/fpm-php5.4/php-fpm.conf file with the following contents (existing contents can be deleted):

[global]
error_log = /var/log/php-fpm.log
log_level = notice

[docs]
listen = /var/run/docs.php-fpm.socket
listen.allowed_clients = 127.0.0.1
listen.owner = docs
listen.group = nginx
listen.mode = 0660
user = docs
group = docs
pm = dynamic
pm.max_children = 16
pm.start_servers = 2
pm.min_spare_servers = 2
pm.max_spare_servers = 2
pm.max_requests = 500
php_admin_value[open_basedir] = /home/docs/public_html:/tmp
php_admin_value[error_log] = /home/docs/php-errors.log
php_admin_value[disable_functions] = exec, system, shell_exec, passthru, popen, dl, curl_multi_exec, posix_getpwuid, 
 disk_total_space, disk_free_space, escapeshellcmd, escapeshellarg, eval, get_current_user, getmyuid, getmygid, 
 posix_getgrgid, parse_ini_file, proc_get-status, proc_nice, proc_terminate, suexec, pclose, virtual, set_time_limit, show_source

This configuration file tells PHP to use the docs user when running MediaWiki. Please note that the last line is very long - I have split it into 3 lines for readability on this wiki, but you should combine them into a single line in your configuration file. The line should start with php_admin_value[disable_functions] and end with show_source.

[edit] Configure Nginx

Oh! Now we need to configure nginx to serve pages as the docs user. Assuming your site is named wiki.mysite.com, create a /etc/nginx/sites-available/wiki.mysite.com file with the following contents:

server {
        listen 80;
        server_name wiki.mysite.com;

        access_log /var/log/nginx/wiki.mysite.com.access.log main;
        error_log /var/log/nginx/wiki.mysite.com.error.log error;
        
        root /home/docs/public_html;
        index index.html index.php;

        # uncomment this if you want to htpasswd-protect your site while you set it up initially
        # auth_basic "Ninjas allowed only";
        # auth_basic_user_file /etc/nginx/docs.funtoo.org.htpasswd;

location ~* ^(.*)(install.php|LocalSettings.php|\.git) { deny all; }

location ~* \.php$ {
        #set $https "off"; 
        #if ($scheme = https) { set $https "on"; }
        #fastcgi_param HTTPS $https;

        try_files       $uri    @404;
        fastcgi_param   GATEWAY_INTERFACE  CGI/1.1;
        fastcgi_param   SERVER_SOFTWARE    nginx;
        fastcgi_param   QUERY_STRING       $query_string;
        fastcgi_param   REQUEST_METHOD     $request_method;
        fastcgi_param   CONTENT_TYPE       $content_type;
        fastcgi_param   CONTENT_LENGTH     $content_length;
        fastcgi_param   SCRIPT_FILENAME    $document_root$fastcgi_script_name;
        fastcgi_param   SCRIPT_NAME        $fastcgi_script_name;
        fastcgi_param   REQUEST_URI        $request_uri;
        fastcgi_param   DOCUMENT_URI       $document_uri;
        fastcgi_param   DOCUMENT_ROOT      $document_root;
        fastcgi_param   SERVER_PROTOCOL    $server_protocol;
        fastcgi_param   REMOTE_ADDR        $remote_addr;
        fastcgi_param   REMOTE_PORT        $remote_port;
        fastcgi_param   SERVER_ADDR        $server_addr;
        fastcgi_param   SERVER_PORT        $server_port;
        fastcgi_param   SERVER_NAME        wiki.mysite.com;

        fastcgi_pass    unix:/var/run/docs.php-fpm.socket;
        fastcgi_index   index.php;
}

# this will secure the MediaWiki uploads against arbitrary PHP injection attacks:
location /images/ {
        location ~.*\.(php)?$ {
                deny all;
        }
}


location @404 {
        return 404;
        break;
}

location / {
        try_files $uri $uri/ @mediawiki;
}

location @mediawiki {
        rewrite ^/([^?]*)(?:\?(.*))? /index.php?title=$1&$2 last;
}

}

[edit] Enable Ngnix and PHP-FPM

Now, let's enable nginx to serve our site, and also be sure to enable php-fpm:

# cd /etc/nginx/sites-enabled
# ln -s ../sites-available/wiki.mysite.com wiki.mysite.com
# rc-update add nginx default
# rc-update add php-fpm default
# rc
 * Starting PHP FastCGI Process Manager ...                                                            [ ok ]
 * Starting nginx ...                                                                                  [ ok ]
#

[edit] Download MediaWiki

We're getting close. Now, head to http://www.mediawiki.org/wiki/Download and copy the link address for the latest version of MediaWiki, currently 1.19.1 at the time this was written. Let's download the archive to /var/tmp:

# cd /var/tmp
# wget http://download.wikimedia.org/mediawiki/1.19/mediawiki-1.19.1.tar.gz

[edit] Extract MediaWiki

We now have all the Web, database and email infrastructure enabled that we need. Heading to the IP address of your server should result in a 404 - Not Found error in your Web browser. Time to extract and configure MediaWiki itself:

# su docs
$ cd /var/tmp
$ tar xvf ./mediawiki-1.19.1.tar.gz
$ mv mediawiki-1.19.1 ~/public_html

[edit] MediaWiki from GIT

Alternatively, we can download the code from the git repository:

# su docs
$ cd ~
$ git clone https://gerrit.wikimedia.org/r/p/mediawiki/core.git public_html

Specific stable versions of MediaWiki are tracked using 'tags'. These are analogous to the tarball releases. We can see the versions available with:

$ cd public_html
$ git tag -l | sort -V

To use a specific tag (1.19.1):

$ git checkout 1.19.1

[edit] Initial Web Config

You will now be able to load the URL of your server in your Web browser and configure MediaWiki through the Web user interface. Complete the full installation process and be sure to specify that you are using XCache for caching. Once you go through this process, the Web installation process will provide you with a LocalSettings.php file, which you should place in /home/docs/public_html. The LocalSettings.php file can also be manually edited and used to enable MediaWiki features and extensions.

[edit] Tips and Tricks

[edit] ArticlePath

By default, MediaWiki pages will have a URL of wiki.myserver.com/index.php?title=PageName. With a few minor tweaks, you can tell MediaWiki to use wiki.myserver.com/PageName instead. Here's how. Open up LocalSettings.php and search for the $wgScriptPath line. This part of the config will look like this:

$wgScriptPath       = "";
$wgScriptExtension  = ".php";

Change this part of the file to look like this:

$wgScriptPath       = "";
$wgArticlePath      = "/$1";
$wgUsePathInfo      = true;
$wgScriptExtension  = ".php";

The old-style URLs will still work, but the shorter more intuitive URLs will now be used for all wiki links.

[edit] $wgSpamRegex

You may find that your wiki is the target of spammers. The easiest way to combat spam is to set $wgSpamRegex in LocalSettings.php, like so:

$wgSpamRegex = "/badword1|badword2|badword3/i"

This will perform a case-insensitive match against the bad words and block anyone from saving edits that contain these words.

[edit] DNS Blacklist

MediaWiki also has the ability to consult a DNS blacklist to prevent known forum and wiki spam sites from performing any edits on your wiki. To enable this capability, add the following to LocalSettings.php:

$wgEnableDnsBlacklist = true;
$wgDnsBlacklistUrls = array( 'xbl.spamhaus.org', 'opm.tornevall.org' );

You may notice a significant decrease in spam posts.

[edit] $wgServer

Here is an important tip -- the $wgServer variable in LocalSettings.php defines the URL of your MediaWiki installation. MediaWiki will encode this within its HTML replies, which means that the Web browser from which you are accessing MediaWiki must be able to reach your server using this address, or pages will not display. This is not a security feature in any way, but a configuration issue. For example, if $wgServer is set to 10.0.1.128, then the only systems that will be able to access your MediaWiki installation are those for which 10.0.1.128 resolves to your MediaWiki installation. The same is true of non-IP $wgServer entries like wiki.mysite.com. If you are setting up a test wiki, you may need a temporary entry in a desktop's /etc/hosts file so that it can interact with the wiki properly before DNS is set up.

[edit]

If you want to change the wiki logo, edit LocalSettings.php and replace $wgLogo with the location of the image you want to use:

$wgLogo = "image.png"
Note: The above references the file image.png in the directory /home/docs/public_html