Difference between pages "Package:MediaWiki" and "Package:Nginx"

(Difference between pages)
m (add some media, 200 vidz, strip page needing updates warning because this page is completely excellent. (it just needs some nginx stuff moved to the nginx page))
 
m (add up some php caching.)
 
Line 1: Line 1:
 
{{Ebuild
 
{{Ebuild
|Summary=
+
|Summary=Robust, small and high performance HTTP and reverse proxy server
|CatPkg=www-apps/mediawiki
+
|CatPkg=www-servers/nginx
|Maintainer=Drobbins,
+
|Maintainer=Drobbins
 
|Repository=Funtoo Overlay
 
|Repository=Funtoo Overlay
}}
+
|Overlay=Funtoo
 +
}}  
 +
[[Image:nginx.gif|frame]]
  
{{Fancyimportant|1=
+
nginx (pronounced "engin-x") is a Web and reverse proxy server for HTTP, SMTP, POP3 and IMAP protocols. It focuses on high concurrency, performance and low memory usage. Nginx quickly delivers static content with efficient use of system resources, also dynamic content is delivered on a network using FastCGI, SCGI handlers for scripts, uWSGI application servers or Phusion Passenger module (atm broken in [http://funtoo.org funtoo]), further more it can serve a very capable software load balancer. It uses an asynchronos event-driven approach to handle requests which provides more predictable performance under load, in contrast to the Apache HTTP server model, that uses a threaded or process-oriented approach to handling request. Nginx is licensed under a BSD-like license and it runs on Unix, Linux, BSD variants, Mac OS X, Solaris, AIX and Microsoft Windows.  
This page documents how to install MediaWiki from source tarball rather than portage, which is the preferred method. It also shows how to use MediaWiki with php-5.4. As of late 1.22 and 1.23, MediaWiki now unofficially works with php-5.5 & php-5.6.}}
+
  
MediaWiki is a [[Web-server-stack]] web application.  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 good performance. We will also properly secure MediaWiki, and also cover some additional tips and tricks, focusing on spam reduction.
+
=== USE Expanded flags ===
 
+
== Portage Settings ==
+
 
+
Add the following line to <code>/etc/[[make.conf]]</code>:
+
 
+
 
+
<pre>
+
PHP_TARGETS="php5-4"
+
</pre>
+
 
+
Add the following lines to <code>/etc/portage/package.use/php</code>:
+
 
+
<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>
+
  
== Emerge ==
+
Furthermore, you can set the nginx modules you like to use in ''/etc/make.conf'' in the NGINX_MODULES_HTTP variable as NGINX_MODULES_HTTP="variables".
  
Emerge xcache, and we'll also emerge metalog and postfix. This should pull in MySQL as well as php-5.4:
+
nginx USE flags go into ''/etc/portage/package.use'' or ''/etc/portage/package.use/nginx'', while the HTTP and MAIL modules go as NGINX_MODULES_HTTP or NGINX_MODULES_MAIL are stored in /etc/make.conf. And as you wouldn't server only static html files, but most commonly also php files/scripts you should also install php with fpm enabled and xcache for caching the content, what makes your nginx setup way faster. For xcache you need to set PHP_TARGETS="php5-3" in '/etc/make.conf'.
  
 +
Example:
 
<console>
 
<console>
# ##i##emerge --jobs xcache metalog postfix
+
###i## echo "www-servers/nginx USE-FLAG-List" >> /etc/portage/package.use/nginx
 
</console>
 
</console>
  
== Start and Configure Services ==
+
=== Emerging nginx ===
 
+
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:
+
  
 +
Now you are ready to install nginx with php and xcache support:
 
<console>
 
<console>
# ##i##emerge --config mysql
+
###i## emerge -avt nginx php xcache
# ##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>
 
</console>
 +
so now just check your useflags and press enter to start emerge.
  
== Database Setup ==
+
== Configuring ==
  
Now, let's create a database named <code>mediawiki</code> for use by MediaWiki, and a <code>mediawiki@localhost</code> user to access this database, using a password of <code>wikifever</code>:
+
All configuration is done in ''/etc/nginx'' with ''nginx.conf'' as the main configuration file and all virtual hosts in ''/etc/nginx/sites/available'' while you have to symlink ''/etc/nginx/sites-available/{VHOST}'' to ''/etc/nginx/sites-enabled/{VHOST}'' to activate them. An example config for such a {VHOST} looks like that:
 
+
<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 <code>docs</code> user, for security. Let's set up a <code>docs</code> 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 <code>/etc/php/fpm-php5.4/php-fpm.conf</code> file with the following contents (existing contents can be deleted):
+
 
+
{{file|name=/etc/php/fpm-php5.4/php-fpm.conf|desc= |body=
+
[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 <code>docs</code> 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 <code>php_admin_value[disable_functions]</code> and end with <code>show_source</code>.
+
 
+
== 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 <code>/etc/nginx/sites-available/wiki.mysite.com</code> file with the following contents:
+
  
 
<pre>
 
<pre>
 
server {
 
server {
        listen 80;
+
    listen         80;
        server_name wiki.mysite.com;
+
    server_name     www.example.com;
  
        access_log /var/log/nginx/wiki.mysite.com.access.log main;
+
    access_log     /var/log/nginx/www.example.com.access_log main;
        error_log /var/log/nginx/wiki.mysite.com.error.log error;
+
    error_log       /var/log/nginx/www.example.com.error_log info;
       
+
        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
+
    root /var/www/www.example.com/htdocs;
        # auth_basic "Ninjas allowed only";
+
}
        # auth_basic_user_file /etc/nginx/docs.funtoo.org.htpasswd;
+
</pre>
  
location ~* ^(.*)(install.php|LocalSettings.php|\.git) { deny all; }
+
The ''nginx.conf'' and ''sites-available/localhost'' file is well commented. Customize it to your needs. Make sure you set the listen option correctly. By default, the listen option is set to listen on the loopback interface. If you leave this unchanged other computers on the network will not be able to connect to the server.  
  
location ~* \.php$ {
+
=== php-fpm ===
        #set $https "off";
+
        #if ($scheme = https) { set $https "on"; }
+
        #fastcgi_param HTTPS $https;
+
  
        try_files      $uri    @404;
+
nginx does not natively support php, so we delegate that responsibility to [[Package:Php#Fpm | php-fpm]]
        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;
+
{{file|name=/etc/nginx/sites-available/localhost|desc=fpm configuration|body=
         fastcgi_index  index.php;
+
server {
}
+
         ...
 
+
index index.php index.cgi index.htm index.html;
# this will secure the MediaWiki uploads against arbitrary PHP injection attacks:
+
location ~ .php$ {
location /images/ {
+
        fastcgi_pass 127.0.0.1:9000;
        location ~.*\.(php)?$ {
+
include fastcgi.conf;
                deny all;
+
 
         }
 
         }
 +
        ...
 
}
 
}
 
 
location @404 {
 
        return 404;
 
        break;
 
}
 
 
location / {
 
        try_files $uri $uri/ @mediawiki;
 
}
 
 
location @mediawiki {
 
        rewrite ^/([^?]*)(?:\?(.*))? /index.php?title=$1&$2 last;
 
}
 
 
}
 
</pre>
 
 
for localhost/wiki/ short urls in nginx:
 
{{file|name=/etc/nginx/sites-enabled/localhost|lang=|desc=domain.com/wiki/ short urls|body=
 
location /wiki {
 
index index.php;
 
rewrite "^(wiki)$" $1/ permanent;
 
rewrite "^/?wiki(/.*)?" /mediawiki/index.php?title=$1&$args last;
 
 
 
}}
 
}}
  
== Enable Ngnix and PHP-FPM ==
+
==== php caching ====
 
+
{{file|name=/etc/nginx/sites-available/localhost|desc=fpm cache configuration|body=
Now, let's enable nginx to serve our site, and also be sure to enable php-fpm:
+
fastcgi_cache_path /etc/nginx/cache levels=1:2 keys_zone=MYAPP:100m inactive=60m;
 
+
fastcgi_cache_key "$scheme$request_method$host$request_uri";
<console>
+
server {
# ##i##cd /etc/nginx/sites-enabled
+
...
# ##i##ln -s ../sites-available/wiki.mysite.com wiki.mysite.com
+
        location ~ \.php$ {
# ##i##rc-update add nginx default
+
...
# ##i##rc-update add php-fpm default
+
fastcgi_cache MYAPP;
# ##i##rc
+
fastcgi_cache_valid 200 60m;
* Starting PHP FastCGI Process Manager ...                                                            [ ok ]
+
* Starting nginx ...                                                                                  [ ok ]
+
#
+
</console>
+
 
+
== MediaWiki from portage ==
+
There are mediawiki ebuilds in portage, if you like your site breaking upon emerge --sync && emerge -avuND world:
+
 
+
<console>###i## emerge mediawiki</console>
+
 
+
With out the vhost flag the files will be dropped into /var/www/localhost/htdocs/mediawiki.
+
 
+
== 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 <code>/var/tmp</code>:
+
 
+
<console>
+
# ##i##cd /var/tmp
+
# ##i##wget http://download.wikimedia.org/mediawiki/1.19/mediawiki-1.19.1.tar.gz
+
</console>
+
 
+
== 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:
+
 
+
<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>
+
 
+
== MediaWiki from GIT ==
+
 
+
Alternatively, we can download the code from the git repository:
+
 
+
<console>
+
# ##i##su docs
+
$ ##i##cd ~
+
$ ##i##git clone https://gerrit.wikimedia.org/r/p/mediawiki/core.git public_html
+
</console>
+
 
+
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>
+
 
+
To use a specific tag (1.19.1):
+
<console>
+
$ ##i##git checkout 1.19.1
+
</console>
+
 
+
== 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 <code>LocalSettings.php</code> file, which you should place in <code>/home/docs/public_html</code>. The <code>LocalSettings.php</code> file can also be manually edited and used to enable MediaWiki features and extensions.
+
 
+
== Tips and Tricks ==
+
 
+
=== Alternate Main Page ===
+
To define your default landing page for mediawiki.
+
edit: localhost/wiki/MediaWiki:Mainpage
+
 
+
example: http://www.funtoo.org/MediaWiki:Mainpage
+
 
+
=== Show Php handler, Database & Plugins Used ===
+
To show which plugins are installed on a wiki, browse localhost/wiki/Special:Version.
+
 
+
example: http://funtoo.org/Special:Version
+
 
+
=== Sidebar ===
+
To define your own sidebar links, edit localhost/wiki/MediaWiki:Sidebar
+
 
+
links follow the page|text format.  example:
+
http://www.funtoo.org/MediaWiki:Sidebar
+
 
+
=== Rss subscriptions ===
+
Rss is handy to track page changes.  all individual pages can be tracked for changes under mediawiki.  For example, if you wish to track your user talk pages via rss, go to your talk page, navigate to history.  add &feed=rss to the end.  &feed=atom is also valid.
+
 
+
http://www.funtoo.org/index.php?title=User:Drobbins&action=history&feed=rss
+
 
+
 
+
=== ArticlePath ===
+
 
+
By default, MediaWiki pages will have a URL of <code>wiki.myserver.com/index.php?title=PageName</code>. With a few minor tweaks, you can tell MediaWiki to use <code>wiki.myserver.com/PageName</code> instead. Here's how. Open up <code>LocalSettings.php</code> and search for the <code>$wgScriptPath</code> line. This part of the config will look like this:
+
 
+
<pre>
+
$wgScriptPath      = "";
+
$wgScriptExtension  = ".php";
+
</pre>
+
 
+
Change this part of the file to look like this:
+
 
+
<pre>
+
$wgScriptPath      = "";
+
$wgArticlePath      = "/$1";
+
$wgUsePathInfo      = true;
+
$wgScriptExtension  = ".php";
+
</pre>
+
 
+
The old-style URLs will still work, but the shorter more intuitive URLs will now be used for all wiki links.
+
 
+
=== $wgSpamRegex ===
+
 
+
You may find that your wiki is the target of spammers. The easiest way to combat spam is to set <code>$wgSpamRegex</code> in <code>LocalSettings.php</code>, like so:
+
 
+
<pre>
+
$wgSpamRegex = "/badword1|badword2|badword3/i"
+
</pre>
+
 
+
This will perform a case-insensitive match against the bad words and block anyone from saving edits that contain these words.
+
 
+
=== 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 <code>LocalSettings.php</code>:
+
 
+
<pre>
+
$wgEnableDnsBlacklist = true;
+
$wgDnsBlacklistUrls = array( 'xbl.spamhaus.org', 'opm.tornevall.org' );
+
</pre>
+
 
+
You may notice a significant decrease in spam posts.
+
 
+
=== $wgRawHtml ===
+
 
+
{{warning|raw html can be dangerous regarding injecting spam/malicious/fishing pages.  use with care!}}
+
 
+
To allow any raw html inserted into your wiki:
+
 
+
{{file|name=/var/www/localhost/htdocs/mediawiki/LocalSettings.php|lang=php|desc=enabling arbitrary html|body=
+
 
...
 
...
$wgRawHtml = "true";
 
 
}}
 
}}
 +
[https://www.digitalocean.com/community/tutorials/how-to-setup-fastcgi-caching-with-nginx-on-your-vps for more information on php caching]
  
=== $wgServer ===
+
=== proxy_pass===
 +
This configuration proxies to other webservers.  In this example we have webrick running on port 3000 behind nginx producing the live link http://localhost/rails
  
Here is an important tip -- the <code>$wgServer</code> variable in <code>LocalSettings.php</code> 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 <code>$wgServer</code> is set to <code>10.0.1.128</code>, then the only systems that will be able to access your MediaWiki installation are those for which <code>10.0.1.128</code> resolves to your MediaWiki installation.  The same is true of non-IP <code>$wgServer</code> entries like <code>wiki.mysite.com</code>. If you are setting up a test wiki, you may need a temporary entry in a desktop's <code>/etc/hosts</code> file so that it can interact with the wiki properly before DNS is set up.
+
{{file|name=/etc/nginx/sites-available/localhost|desc=rails or python configurations|body=
 +
server {
 +
        ...
 +
location /rails/ {
 +
    proxy_set_header Host $host;
 +
    proxy_set_header X-Real-IP $remote_addr;
 +
    proxy_pass http://127.0.0.1:3000/; #for ruby on rails webrick
 +
            #proxy_pass http://127.0.0.1:8000/; #for python -m http.server
 +
            #proxy_pass http://127.0.0.1:8080/; #for other web servers like apache, lighttpd, tengine, cherokee, etc...
 +
}
 +
        ...
 +
}
 +
}}
  
=== $wgLogo ===
+
== Location Processing Order ==
 +
One often confusing aspect of nginx configuration is the order in which it processes location directives. This section is intended to clarify the confusion and help you to write secure nginx location directives.
  
If you want to change the wiki logo, edit <code>LocalSettings.php</code> and replace $wgLogo with the location of the image you want to use:
+
=== Two basic types of Location directives ===
 +
There are two basic types of location directives. The first is called a "conventional string", and looks something like this:
 +
location /foo { deny all; }
 +
The second basic type of location directive is a regex, or regular expression block. In its most basic form, it looks like this, with a "~" and then a regular expression that is matched against the request path. "^" can be used to match the beginning of the request path, and "$" can be used to match the end of the request path. If you need to match a ".", you must escape it as "\." as per regular expression matching rules:
 +
location ~ \.php$ { blah; }
  
<pre>
+
=== The basic algorithm ===
$wgLogo = "image.png"
+
Nginx uses a special algorithm to find the proper location string to match the incoming request. The basic concept to remember is that conventional string directives are placed in one "bucket", and then regular expression strings are placed in another "bucket". Nginx will use the first regular expression match that it finds, when scanning the file from top to bottom. If no matching regular expression is found, nginx will look in its "conventional string" bucket, and try to find a match. In the case of the conventional string matches, the most ''specific'' match will be used, in other words, the one will be used that matches the greatest number of characters in the request path.
</pre>
+
{{fancynote| The above references the file <code>image.png</code> in the directory <code>/home/docs/public_html</code>}}
+
  
=== MySQL wildcard searches ===
+
This is the foundation for nginx location processing, so always use these rules as a starting point for understanding location matching order. Nginx then provides various sub-types of location directives which modify this default behavior in a number of ways. This will be covered in the next section.
Recent versions of mediawiki have broken search results.
+
  
{{file|name=/var/www/localhost/htdocs/mediawiki/includes/search/SearchMySQL.php|lang=php|desc=line 175 modification to repair mysql searches|body=
+
== Advanced Location Processing ==
if ( trim( $term ) === '' ) {
+
Always use the location processing logic described in the previous section as the foundation for understanding how nginx finds a matching location directive, and then once you are comfortable with how this works, read about these more advanced directives and understand how they fit into nginx's overall logic.
return null;
+
} else {
+
$term = $term . '*';
+
}
+
}}
+
  
=== License Badges ===
+
=== = (equals) Location ===
You can have licenses displayed with your pages.
+
One advanced location directive is the "=" location, which can be considered a variant of a "conventional string" directive. "=" directives are searched before all other directives, and if a match found, then the corresponding location block is used. A "=" location must the requested path ''exactly'' and ''completely''. For example, the following location block will match only the request /foo/bar, but not /foo/bar/oni.html:
 +
location = /foo/bar { deny all; }
  
{{file|name=/var/www/localhost/htdocs/mediawiki/LocalSettings.php|lang=php|desc=add license badge to articles|body=
+
=== ~* (case-insensitive regex) Location ===
$wgRightsPage = ""; # Set to the title of a wiki page that describes your license/copyright
+
A "~*" regex match is just like a regular "~" regex match, except matches will be performed in a case-insensitive manner. "~*" location directives, being regex directives, fall into the regex "bucket" and are processed along other regex directives. This means that they are processed in the order they appear in your configuration file and the first match will be used -- assuming no "=" directives match.
$wgRightsUrl = "http://creativecommons.org/licenses/by-sa/3.0/"; //external source explaining license
+
$wgRightsText = "Creative Commons Attribution Share Alike"; //alternate text on the image
+
$wgRightsIcon = "{$wgStylePath}/common/images/cc-by-sa.png";
+
}}
+
  
There are 6 possible badge images
+
=== ^~ (short-circuit conventional string) Location ===
 +
You may think that a "^~" location is a regex location, but it is not. It is a variant of a conventional string location. If you recall, nginx will search for conventional string matches by finding the ''most specific'' match. However, when you use a "^~" location, nginx behavior is modified. Imagine the way a conventional string match works. Nginx scans your configuration file, looking at each conventional string match from line 1 to the end of file, but it scans ''all'' conventional string matches to find the ''best'' match. Well, the "~^" location match short-circuits this process. If, in the process of scanning each conventional string match in the config file, nginx encounters a "^~" match that matches the current request path, then nginx will apply this match, and stop looking for the ''best'' match.
  
* {$wgStylePath}/common/images/cc-0.png
+
== Ebuild Update Protocol ==
* {$wgStylePath}/common/images/cc-by-nc-sa.png
+
* {$wgStylePath}/common/images/cc-by-sa.png
+
* {$wgStylePath}/common/images/cc-by.png
+
* {$wgStylePath}/common/images/gnu-fdl.png
+
* {$wgStylePath}/common/images/public-domain.png
+
  
=== Importing Google Fonts & External Css ===
+
To work on a new version of the ebuild, perform the following steps.
Googles font api is excellent.  all you have to do is look through https://www.google.com/fonts# and select which font you want.  To the bottom right of the font pane is a little box with an arrow pointing right.  click the arrow, and follow step 1, and 2.  for step 3 you need to select @import.  on your wiki navigate to localhost/MediaWiki:Common.css or a specific skin to add the css to like localhost/MediaWiki:Vector.css and enter this code.
+
  
{{file|name=localhost/MediaWiki:Common.css|lang=css|desc=|body=
+
First, temporarily set the following settings in <tt>/etc/make.conf</tt>:
@import url(http://fonts.googleapis.com/css?family=Lobster);
+
 
+
.firstHeading, #mw-head, .body ul li {
+
font-family: 'Lobster', cursive;
+
}
+
}}
+
 
+
External css is similar, if you wanted to bootswatch your wiki navigate to http://www.bootstrapcdn.com/#bootswatch_tab select which cdn and insert it into your common css.
+
 
+
{{file|name=localhost/MediaWiki:Common.css|lang=css|desc=yeti for the sasquatch hunter in you|body=
+
@import url(//maxcdn.bootstrapcdn.com/bootswatch/3.2.0/yeti/bootstrap.min.css);
+
}}
+
  
== Media ==
+
<syntaxhighlight lang="bash">
{{#widget:YouTube|playlist=PL7ABDor6eEgc2U9PH4Irty4K8mqUgkvDq}}
+
NGINX_MODULES_HTTP="*"
 +
NGINX_MODULES_MAIL="*"
 +
</syntaxhighlight>
  
== External Resources ==
+
This will enable all available modules for nginx.
* http://www.mediawiki.org/wiki/Manual:System_administration
+
* http://www.mediawiki.org/wiki/Manual:Performance_tuning
+
* http://www.mediawiki.org/wiki/Help:Templates
+
* http://www.mediawiki.org/wiki/Transclusion
+
  
[[Category:Featured]]
+
Now, create a new version of the ebuild in your overlay, and look at all the modules listed at the top of the ebuild. Visit the URLs in the comments above each one and ensure that the latest versions of each are included. Now run <tt>ebuild nginx-x.y.ebuild clean install</tt> to ensure that all modules patch/build properly. Basic build testing is now complete.
[[Category:HOWTO]]
+
[[Category:Official Documentation]]
+
[[Category:Ebuilds]]
+
 
{{EbuildFooter}}
 
{{EbuildFooter}}

Latest revision as of 04:34, November 16, 2014

www-servers/nginx


Current Maintainer(s):Daniel Robbins
Source Repository:Funtoo Overlay

Summary: Robust, small and high performance HTTP and reverse proxy server

Use Flags

addition
Enables HTTP addition filter module
aio
Enables file AIO support
flv
Enables special processing module for flv files
http
Enable HTTP core support
http-cache
Enable HTTP cache support
libatomic
Use libatomic instead of builtin atomic operations
pop
Enables POP3 proxy support
random-index
Enables HTTP random index module
realip
Enables realip module
smtp
Enables SMTP proxy support
static-gzip
Enables support for gzipping static content
status
Enables stub_status module
sub
Enables sub_filter module
webdav
Enable webdav support

Nginx

Nginx.gif

nginx (pronounced "engin-x") is a Web and reverse proxy server for HTTP, SMTP, POP3 and IMAP protocols. It focuses on high concurrency, performance and low memory usage. Nginx quickly delivers static content with efficient use of system resources, also dynamic content is delivered on a network using FastCGI, SCGI handlers for scripts, uWSGI application servers or Phusion Passenger module (atm broken in funtoo), further more it can serve a very capable software load balancer. It uses an asynchronos event-driven approach to handle requests which provides more predictable performance under load, in contrast to the Apache HTTP server model, that uses a threaded or process-oriented approach to handling request. Nginx is licensed under a BSD-like license and it runs on Unix, Linux, BSD variants, Mac OS X, Solaris, AIX and Microsoft Windows.

USE Expanded flags

Furthermore, you can set the nginx modules you like to use in /etc/make.conf in the NGINX_MODULES_HTTP variable as NGINX_MODULES_HTTP="variables".

nginx USE flags go into /etc/portage/package.use or /etc/portage/package.use/nginx, while the HTTP and MAIL modules go as NGINX_MODULES_HTTP or NGINX_MODULES_MAIL are stored in /etc/make.conf. And as you wouldn't server only static html files, but most commonly also php files/scripts you should also install php with fpm enabled and xcache for caching the content, what makes your nginx setup way faster. For xcache you need to set PHP_TARGETS="php5-3" in '/etc/make.conf'.

Example:

# echo "www-servers/nginx USE-FLAG-List" >> /etc/portage/package.use/nginx

Emerging nginx

Now you are ready to install nginx with php and xcache support:

# emerge -avt nginx php xcache

so now just check your useflags and press enter to start emerge.

Configuring

All configuration is done in /etc/nginx with nginx.conf as the main configuration file and all virtual hosts in /etc/nginx/sites/available while you have to symlink /etc/nginx/sites-available/{VHOST} to /etc/nginx/sites-enabled/{VHOST} to activate them. An example config for such a {VHOST} looks like that:

server {
    listen          80;
    server_name     www.example.com;

    access_log      /var/log/nginx/www.example.com.access_log main;
    error_log       /var/log/nginx/www.example.com.error_log info;

    root /var/www/www.example.com/htdocs;
}

The nginx.conf and sites-available/localhost file is well commented. Customize it to your needs. Make sure you set the listen option correctly. By default, the listen option is set to listen on the loopback interface. If you leave this unchanged other computers on the network will not be able to connect to the server.

php-fpm

nginx does not natively support php, so we delegate that responsibility to php-fpm

/etc/nginx/sites-available/localhost: fpm configuration
server {
        ...
	index index.php index.cgi index.htm index.html;
	location ~ .php$ {
	        fastcgi_pass 127.0.0.1:9000;
		include fastcgi.conf;
        }
        ...
}

php caching

/etc/nginx/sites-available/localhost: fpm cache configuration
fastcgi_cache_path /etc/nginx/cache levels=1:2 keys_zone=MYAPP:100m inactive=60m;
fastcgi_cache_key "$scheme$request_method$host$request_uri";
server {
...
        location ~ \.php$ {
...
		fastcgi_cache MYAPP;
		fastcgi_cache_valid 200 60m;
...

for more information on php caching

proxy_pass

This configuration proxies to other webservers. In this example we have webrick running on port 3000 behind nginx producing the live link http://localhost/rails

/etc/nginx/sites-available/localhost: rails or python configurations
server {
        ...
	location /rails/ {
	    proxy_set_header Host $host;
	    proxy_set_header X-Real-IP $remote_addr;
	    proxy_pass http://127.0.0.1:3000/; #for ruby on rails webrick
            #proxy_pass http://127.0.0.1:8000/; #for python -m http.server
            #proxy_pass http://127.0.0.1:8080/; #for other web servers like apache, lighttpd, tengine, cherokee, etc...
	}
        ...
}

Location Processing Order

One often confusing aspect of nginx configuration is the order in which it processes location directives. This section is intended to clarify the confusion and help you to write secure nginx location directives.

Two basic types of Location directives

There are two basic types of location directives. The first is called a "conventional string", and looks something like this:

location /foo { deny all; }

The second basic type of location directive is a regex, or regular expression block. In its most basic form, it looks like this, with a "~" and then a regular expression that is matched against the request path. "^" can be used to match the beginning of the request path, and "$" can be used to match the end of the request path. If you need to match a ".", you must escape it as "\." as per regular expression matching rules:

location ~ \.php$ { blah; }

The basic algorithm

Nginx uses a special algorithm to find the proper location string to match the incoming request. The basic concept to remember is that conventional string directives are placed in one "bucket", and then regular expression strings are placed in another "bucket". Nginx will use the first regular expression match that it finds, when scanning the file from top to bottom. If no matching regular expression is found, nginx will look in its "conventional string" bucket, and try to find a match. In the case of the conventional string matches, the most specific match will be used, in other words, the one will be used that matches the greatest number of characters in the request path.

This is the foundation for nginx location processing, so always use these rules as a starting point for understanding location matching order. Nginx then provides various sub-types of location directives which modify this default behavior in a number of ways. This will be covered in the next section.

Advanced Location Processing

Always use the location processing logic described in the previous section as the foundation for understanding how nginx finds a matching location directive, and then once you are comfortable with how this works, read about these more advanced directives and understand how they fit into nginx's overall logic.

= (equals) Location

One advanced location directive is the "=" location, which can be considered a variant of a "conventional string" directive. "=" directives are searched before all other directives, and if a match found, then the corresponding location block is used. A "=" location must the requested path exactly and completely. For example, the following location block will match only the request /foo/bar, but not /foo/bar/oni.html:

location = /foo/bar { deny all; }

~* (case-insensitive regex) Location

A "~*" regex match is just like a regular "~" regex match, except matches will be performed in a case-insensitive manner. "~*" location directives, being regex directives, fall into the regex "bucket" and are processed along other regex directives. This means that they are processed in the order they appear in your configuration file and the first match will be used -- assuming no "=" directives match.

^~ (short-circuit conventional string) Location

You may think that a "^~" location is a regex location, but it is not. It is a variant of a conventional string location. If you recall, nginx will search for conventional string matches by finding the most specific match. However, when you use a "^~" location, nginx behavior is modified. Imagine the way a conventional string match works. Nginx scans your configuration file, looking at each conventional string match from line 1 to the end of file, but it scans all conventional string matches to find the best match. Well, the "~^" location match short-circuits this process. If, in the process of scanning each conventional string match in the config file, nginx encounters a "^~" match that matches the current request path, then nginx will apply this match, and stop looking for the best match.

Ebuild Update Protocol

To work on a new version of the ebuild, perform the following steps.

First, temporarily set the following settings in /etc/make.conf:

NGINX_MODULES_HTTP="*"
NGINX_MODULES_MAIL="*"

This will enable all available modules for nginx.

Now, create a new version of the ebuild in your overlay, and look at all the modules listed at the top of the ebuild. Visit the URLs in the comments above each one and ensure that the latest versions of each are included. Now run ebuild nginx-x.y.ebuild clean install to ensure that all modules patch/build properly. Basic build testing is now complete.