Difference between revisions of "MythWeb on Nginx"

From MythTV Official Wiki
Jump to: navigation, search
(MythWeb 0.24, nginx 1.4.1, php 5.5.1, and Debian)
 
(15 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{incomplete}}
 
{{incomplete}}
 
+
= TODO =
 
* work in progress - stuarta
 
* work in progress - stuarta
 +
* Perl Backend
  
 +
= Intro =
 
MythWeb provides a web interface for scheduling and managing recordings from a web browser located on any machine, with new features being added such as remote control.
 
MythWeb provides a web interface for scheduling and managing recordings from a web browser located on any machine, with new features being added such as remote control.
  
 
An Apache server can use a lot of memory, especially for a system where the number of users of the server can be measured on one hand...essentially private. [http://www.nginx.org Nginx](pronounced N-Gen-X), is a lightweight, high-performance Web server/reverse proxy.  
 
An Apache server can use a lot of memory, especially for a system where the number of users of the server can be measured on one hand...essentially private. [http://www.nginx.org Nginx](pronounced N-Gen-X), is a lightweight, high-performance Web server/reverse proxy.  
 +
 +
When trying to understand how nginx does things, it's important to remember that it is
 +
a proxy first and a web server second. It just happens to be a blindingly fast web server :)
 +
 +
It is for this reason that you have to install a php backend server as well as a perl backend
 +
server to handle the dynamic generation of content.
  
 
= Installation =
 
= Installation =
Line 16: Line 24:
 
So, we'll assume the root is /var/www/html and that the mythweb directory is right off the root.
 
So, we'll assume the root is /var/www/html and that the mythweb directory is right off the root.
  
 
+
== PHP Backend ==
When trying to understand how nginx does things, it's important to remember that it is
+
=== Fast-CGI for PHP ===
a proxy first and a web server second. It just happens to be a blindingly fast web server :)
 
 
 
It is for this reason that you have to install a php backend server as well as a perl backend
 
server.
 
 
 
=== PHP Backend ===
 
==== Fast-CGI for PHP ====
 
  
 
Unlike Apache, Nginx doesn't have PHP support built in, and it must be configured for it.
 
Unlike Apache, Nginx doesn't have PHP support built in, and it must be configured for it.
Line 31: Line 32:
 
fpm then these instructions should also work for fastcgi.
 
fpm then these instructions should also work for fastcgi.
  
==== PHP FPM ====
+
=== PHP FPM ===
  
 
Ubuntu/Debian have php fpm packages available by default.
 
Ubuntu/Debian have php fpm packages available by default.
Line 40: Line 41:
 
has it listening on 127.0.0.1:9000
 
has it listening on 127.0.0.1:9000
  
=== Perl Backend ===
+
I'd recommend upping the memory limit for php. Edit /etc/php5/fpm/pool.d/www.conf
 +
and modify the following
 +
 
 +
php_admin_value[memory_limit] = 64M
 +
 
 +
and "reload" php5-fpm.
 +
 
 +
== Perl Backend ==
  
 
{{incomplete}}
 
{{incomplete}}
  
== Configuration ==
+
= Configuration =
  
 
Unlike Apache, Nginx does not support .htaccess files, so all configuration must go in the nginx configuration. Of course, for convenience, nginx is defaultly set up to include all files on a conf.d directory, so you can separate out pieces for portability.
 
Unlike Apache, Nginx does not support .htaccess files, so all configuration must go in the nginx configuration. Of course, for convenience, nginx is defaultly set up to include all files on a conf.d directory, so you can separate out pieces for portability.
  
=== /etc/nginx/conf.d/mythweb.include ===
+
== /etc/nginx/conf.d/mythweb.include ==
 
I'd recommend creating a file /etc/nginx/conf.d/mythweb.include with the following contents
 
I'd recommend creating a file /etc/nginx/conf.d/mythweb.include with the following contents
  
 
<code>
 
<code>
    location @handler {
 
        rewrite /mythweb/(.+\.(php|pl))/.*      /mythweb/$1 last;
 
        rewrite /mythweb/(pl(/.*)?)$            /mythweb/mythweb.pl/$1 last;
 
        rewrite /mythweb/(.+)$                  /mythweb/mythweb.php/$1 last;
 
        rewrite /mythweb/(.*)$                  /mythweb/mythweb.php last;
 
    }
 
 
 
     location /mythweb/ {
 
     location /mythweb/ {
 
         auth_basic "MythWeb";
 
         auth_basic "MythWeb";
Line 78: Line 79:
 
         fastcgi_param  hostname mymythbox;
 
         fastcgi_param  hostname mymythbox;
 
         fastcgi_pass    127.0.0.1:9000;
 
         fastcgi_pass    127.0.0.1:9000;
 +
    }
 +
 +
    location @handler {
 +
        rewrite /mythweb/(.+\.(php|pl))/.*      /mythweb/$1 last;
 +
        rewrite /mythweb/(pl(/.*)?)$            /mythweb/mythweb.pl/$1 last;
 +
        rewrite /mythweb/(.+)$                  /mythweb/mythweb.php/$1 last;
 +
        rewrite /mythweb/(.*)$                  /mythweb/mythweb.php last;
 
     }
 
     }
 
</code>
 
</code>
Line 85: Line 93:
 
Entirely up to you.
 
Entirely up to you.
  
=== /etc/nginx/mythweb.passwd ===
+
== /etc/nginx/mythweb.passwd ==
 
You will also need to create /etc/nginx/mythweb.passwd. This is a standard apache style htpasswd
 
You will also need to create /etc/nginx/mythweb.passwd. This is a standard apache style htpasswd
 
file and should contain the username/passwords for authenticating logons to your mythweb install.
 
file and should contain the username/passwords for authenticating logons to your mythweb install.
  
== Rewrite Rules ==
+
== Site Config - /etc/nginx/conf.d/default.conf ==
 +
The default site config is as follows
 +
 
 +
<code>
 +
server {
 +
    listen      80;
 +
    server_name  localhost;
 +
    location / {
 +
        root  /usr/share/nginx/html;
 +
        index  index.html index.htm;
 +
    }
 +
    error_page  500 502 503 504  /50x.html;
 +
    location = /50x.html {
 +
        root  /usr/share/nginx/html;
 +
    }
 +
}
 +
</code>
 +
 
 +
This should be edited to include mythweb.include and update the site root as follows
 +
<code>
 +
server {
 +
    listen      80;
 +
    server_name  localhost;
 +
    root /var/www/html;
 +
    location / {
 +
        index  index.html index.htm;
 +
    }
 +
    include /etc/nginx/conf.d/mythweb.include;
 +
    error_page  500 502 503 504  /50x.html;
 +
    location = /50x.html {
 +
        root  /usr/share/nginx/html;
 +
    }
 +
}
 +
</code>
 +
 
 +
You should now have mythweb running under nginx on localhost. It is left as
 +
an exercise for the reader to configure nginx to listen on a public ip address
 +
so that mythweb is reachable from the outside world.
 +
 
 +
== How it works ==
 +
 
 +
For those that are interested, here's how all that hangs together.
 +
 
 +
===The First Stanza===
 +
First lets examine the first stanza.
 +
<code>
 +
    location /mythweb/ {
 +
        auth_basic "MythWeb";
 +
        auth_basic_user_file mythweb.passwd;
 +
        index /mythweb/mythweb.php;
 +
        try_files $uri @handler;
 +
    }
 +
</code>
 +
 
 +
auth_basic and auth_basic_user_file provide our authentication for mythweb.
  
 +
index tells nginx which file to select when just the directory /mythweb is requested.
  
 +
Then the nginx magic starts.
  
 +
The try_files line makes nginx try to find a file that directly matches the url being requested
 +
For example the mythtv logo is found at /mythweb/skins/default/img/mythtv-logo.png. nginx will find
 +
this file and directly return the content. Anything which cannot be found gets passed to the @handler
 +
stanza which we will look at later.
  
<code>
+
===The second stanza===
    location /mythweb/ {
+
<code>
            root /var/www/html;
+
    location ~ /mythweb/.+\.php {
          # The two Auth Lines assume that you want to password protect - which is recommended
+
        include        fastcgi_params;
            auth_basic          "Restricted";
+
        fastcgi_index  mythweb.php;
          # Supports a standard htpasswd file, which defaults to the same directory as nginx.conf
+
        fastcgi_split_path_info ^(.+\.php)(/?.+)$;
            auth_basic_user_file htpasswd;
+
        fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
            if (!-e $request_filename) {
+
        fastcgi_param   PATH_INFO $fastcgi_path_info;
        rewrite  ^/mythweb/(pl(/.*)?)$       /mythweb/mythweb.pl?PATH_INFO=/$1 last;
+
        fastcgi_param  db_server localhost;
        rewrite   ^/mythweb/(.+)$            /mythweb/mythweb.php?PATH_INFO=/$1 last;
+
        fastcgi_param  db_name  mythconverg;
                }
+
        fastcgi_param  db_login mythtv;
            if (!-f $request_filename) {
+
        fastcgi_param  db_password mythtv;
            rewrite    ^/mythweb/(.*)$                  /mythweb/mythweb.php last;
+
        fastcgi_param  hostname mymythbox;
                }
+
        fastcgi_pass    127.0.0.1:9000;
            }
+
    }
 
</code>
 
</code>
  
== See Also ==
+
This tells nginx that anything which matches the regexp "/mythweb/.+\.php" should be
 +
passed onto the php backend for interpretation.
 +
 
 +
The include file fastcgi_params is the one shipped with the nginx package and contains
 +
all the recommended fastcgi params.
 +
 
 +
fastcgi_split_path_info tells nginx how to split up the request url to correctly populate
 +
the variable $fastcgi_path_info. We need this to set PATH_INFO. If the PHP variable $_SERVER['PATH_INFO']
 +
isn't correctly set, then the whole of mythweb fails to work. Both Apache and lighttpd set this variable
 +
out of the box. The nginx folk consider PATH_INFO depreciated and that the application should do it's magic
 +
based upon the request url instead. Until that time, we have to go and set the PATH_INFO variable correctly :)
 +
 
 +
The fastcgi_param SCRIPT_FILENAME is setting another variable that apache and lighttpd populate by default.
 +
 
 +
=== The @handler Stanza ===
 +
 
 +
<code>
 +
    location @handler {
 +
        rewrite /mythweb/(.+\.(php|pl))/.*      /mythweb/$1 last;
 +
        rewrite /mythweb/(pl(/.*)?)$            /mythweb/mythweb.pl/$1 last;
 +
        rewrite /mythweb/(.+)$                  /mythweb/mythweb.php/$1 last;
 +
        rewrite /mythweb/(.*)$                  /mythweb/mythweb.php last;
 +
    }
 +
</code>
 +
 
 +
This is where all the rewrites happen. This is a translation of the original apache
 +
rewrite ruleset into an nginx rewrite ruleset.
 +
 
 +
Rule 1: This is a terminating rule to make sure we don't spiral down into a rewrite blackhole.
 +
Without this we decend into a rewrite blackhole /mythweb/mythweb.php/mythweb.php/mythweb.php... etc
 +
Once we've done the rewrite to include mythweb.php or mythweb.pl we don't need to rewrite again.
 +
 
 +
Rule 2: This hands off any request starting with /mythweb/pl to the mythweb.pl handler.
 +
 
 +
Rule 3: This is the main workhorse rewrite. It rewrites the pretty urls you see in the browser
 +
to one that feeds the request into mythweb.php. For example requests to /mythweb/status become
 +
/mythweb/mythweb.php/status. This will then match the regexp from stanza two and be fed into
 +
the php backend.
 +
 
 +
Rule 4: This matches anything else not previously matched and send it straight to the main
 +
mythweb.php script. This is primarily used for the front page.
 +
 
 +
 
 +
== MythWeb 0.24, nginx 1.4.1, php 5.5, and Debian ==
 +
 
 +
If running Debian testing/jessie as of Aug 2013, the First Stanza, above, may need to be changed from
 +
        index /mythweb/mythweb.php;
 +
to
 +
        index mythweb.php;
 +
 
 +
If session data is not being saved (for example, if "Settings --> TV --> My Session" has blank date formats), apply the patches from "http://code.mythtv.org/trac/ticket/9833" and "http://code.mythtv.org/trac/ticket/11513".
 +
 
 +
= See Also =
 
* [[MythWeb on Lighttpd]]
 
* [[MythWeb on Lighttpd]]
 
* [[MythWeb]]
 
* [[MythWeb]]
  
 
[[Category:HOWTO]] [[Category:MythWeb]]
 
[[Category:HOWTO]] [[Category:MythWeb]]

Latest revision as of 00:15, 21 September 2013

Incomplete.png Incomplete, needs to be expanded. Please help to fill the gaps or discuss the issue on the talk page

TODO

  • work in progress - stuarta
  • Perl Backend

Intro

MythWeb provides a web interface for scheduling and managing recordings from a web browser located on any machine, with new features being added such as remote control.

An Apache server can use a lot of memory, especially for a system where the number of users of the server can be measured on one hand...essentially private. Nginx(pronounced N-Gen-X), is a lightweight, high-performance Web server/reverse proxy.

When trying to understand how nginx does things, it's important to remember that it is a proxy first and a web server second. It just happens to be a blindingly fast web server :)

It is for this reason that you have to install a php backend server as well as a perl backend server to handle the dynamic generation of content.

Installation

Your distribution should have a package for nginx. It is probably woefully out of date. Do yourself a favour and go and get the packages provided at nginx.org [[1]]

The default HTML directory for the nginx packages is /usr/share/nginx/html, whereas a package of MythWeb goes to the Apache directory.../var/www/html/. You can create a symbolic link, or just have nginx root to the same directory as Apache...a good move if you aren't sure you are going to commit to an alternate web server.

So, we'll assume the root is /var/www/html and that the mythweb directory is right off the root.

PHP Backend

Fast-CGI for PHP

Unlike Apache, Nginx doesn't have PHP support built in, and it must be configured for it. The old way was to use fast-cgi. If you are using nginx, you are trying to get performance and scalability. Forget FastCGI and install php-fpm. If you really have trouble finding php fpm then these instructions should also work for fastcgi.

PHP FPM

Ubuntu/Debian have php fpm packages available by default.

apt-get install php5-fpm

This installs a php fpm instance and the default configuration out of the box has it listening on 127.0.0.1:9000

I'd recommend upping the memory limit for php. Edit /etc/php5/fpm/pool.d/www.conf and modify the following

php_admin_value[memory_limit] = 64M

and "reload" php5-fpm.

Perl Backend

Incomplete.png Incomplete, needs to be expanded. Please help to fill the gaps or discuss the issue on the talk page

Configuration

Unlike Apache, Nginx does not support .htaccess files, so all configuration must go in the nginx configuration. Of course, for convenience, nginx is defaultly set up to include all files on a conf.d directory, so you can separate out pieces for portability.

/etc/nginx/conf.d/mythweb.include

I'd recommend creating a file /etc/nginx/conf.d/mythweb.include with the following contents

   location /mythweb/ {
       auth_basic		"MythWeb";
       auth_basic_user_file	mythweb.passwd;
       index /mythweb/mythweb.php;
       try_files $uri @handler;
   }

   location ~ /mythweb/.+\.php {
       include         fastcgi_params;
       fastcgi_index   mythweb.php;
       fastcgi_split_path_info ^(.+\.php)(/?.+)$;
       fastcgi_param   SCRIPT_FILENAME	$document_root$fastcgi_script_name;
       fastcgi_param   PATH_INFO $fastcgi_path_info;
       fastcgi_param   db_server localhost;
       fastcgi_param   db_name  mythconverg;
       fastcgi_param   db_login mythtv;
       fastcgi_param   db_password mythtv;
       fastcgi_param   hostname mymythbox;
       fastcgi_pass    127.0.0.1:9000;
   }

   location @handler {
       rewrite /mythweb/(.+\.(php|pl))/.*      /mythweb/$1 last;
       rewrite /mythweb/(pl(/.*)?)$            /mythweb/mythweb.pl/$1 last;
       rewrite /mythweb/(.+)$                  /mythweb/mythweb.php/$1 last;
       rewrite /mythweb/(.*)$                  /mythweb/mythweb.php last;
   }

When using php-fpm you can also the php fpm instance to hold the configuration for the database and backend (the fastcgi_param's db_server, db_name, db_login, db_password). Entirely up to you.

/etc/nginx/mythweb.passwd

You will also need to create /etc/nginx/mythweb.passwd. This is a standard apache style htpasswd file and should contain the username/passwords for authenticating logons to your mythweb install.

Site Config - /etc/nginx/conf.d/default.conf

The default site config is as follows

server {

   listen       80;
   server_name  localhost;
   location / {
       root   /usr/share/nginx/html;
       index  index.html index.htm;
   }
   error_page   500 502 503 504  /50x.html;
   location = /50x.html {
       root   /usr/share/nginx/html;
   }

}

This should be edited to include mythweb.include and update the site root as follows server {

   listen       80;
   server_name  localhost;
   root /var/www/html;
   location / {
       index  index.html index.htm;
   }
   include /etc/nginx/conf.d/mythweb.include;
   error_page   500 502 503 504  /50x.html;
   location = /50x.html {
       root   /usr/share/nginx/html;
   }

}

You should now have mythweb running under nginx on localhost. It is left as an exercise for the reader to configure nginx to listen on a public ip address so that mythweb is reachable from the outside world.

How it works

For those that are interested, here's how all that hangs together.

The First Stanza

First lets examine the first stanza.

   location /mythweb/ {
       auth_basic		"MythWeb";
       auth_basic_user_file	mythweb.passwd;
       index /mythweb/mythweb.php;
       try_files $uri @handler;
   }

auth_basic and auth_basic_user_file provide our authentication for mythweb.

index tells nginx which file to select when just the directory /mythweb is requested.

Then the nginx magic starts.

The try_files line makes nginx try to find a file that directly matches the url being requested For example the mythtv logo is found at /mythweb/skins/default/img/mythtv-logo.png. nginx will find this file and directly return the content. Anything which cannot be found gets passed to the @handler stanza which we will look at later.

The second stanza

   location ~ /mythweb/.+\.php {
       include         fastcgi_params;
       fastcgi_index   mythweb.php;
       fastcgi_split_path_info ^(.+\.php)(/?.+)$;
       fastcgi_param   SCRIPT_FILENAME	$document_root$fastcgi_script_name;
       fastcgi_param   PATH_INFO $fastcgi_path_info;
       fastcgi_param   db_server localhost;
       fastcgi_param   db_name  mythconverg;
       fastcgi_param   db_login mythtv;
       fastcgi_param   db_password mythtv;
       fastcgi_param   hostname mymythbox;
       fastcgi_pass    127.0.0.1:9000;
   }

This tells nginx that anything which matches the regexp "/mythweb/.+\.php" should be passed onto the php backend for interpretation.

The include file fastcgi_params is the one shipped with the nginx package and contains all the recommended fastcgi params.

fastcgi_split_path_info tells nginx how to split up the request url to correctly populate the variable $fastcgi_path_info. We need this to set PATH_INFO. If the PHP variable $_SERVER['PATH_INFO'] isn't correctly set, then the whole of mythweb fails to work. Both Apache and lighttpd set this variable out of the box. The nginx folk consider PATH_INFO depreciated and that the application should do it's magic based upon the request url instead. Until that time, we have to go and set the PATH_INFO variable correctly :)

The fastcgi_param SCRIPT_FILENAME is setting another variable that apache and lighttpd populate by default.

The @handler Stanza

   location @handler {
       rewrite /mythweb/(.+\.(php|pl))/.*      /mythweb/$1 last;
       rewrite /mythweb/(pl(/.*)?)$            /mythweb/mythweb.pl/$1 last;
       rewrite /mythweb/(.+)$                  /mythweb/mythweb.php/$1 last;
       rewrite /mythweb/(.*)$                  /mythweb/mythweb.php last;
   }

This is where all the rewrites happen. This is a translation of the original apache rewrite ruleset into an nginx rewrite ruleset.

Rule 1: This is a terminating rule to make sure we don't spiral down into a rewrite blackhole. Without this we decend into a rewrite blackhole /mythweb/mythweb.php/mythweb.php/mythweb.php... etc Once we've done the rewrite to include mythweb.php or mythweb.pl we don't need to rewrite again.

Rule 2: This hands off any request starting with /mythweb/pl to the mythweb.pl handler.

Rule 3: This is the main workhorse rewrite. It rewrites the pretty urls you see in the browser to one that feeds the request into mythweb.php. For example requests to /mythweb/status become /mythweb/mythweb.php/status. This will then match the regexp from stanza two and be fed into the php backend.

Rule 4: This matches anything else not previously matched and send it straight to the main mythweb.php script. This is primarily used for the front page.


MythWeb 0.24, nginx 1.4.1, php 5.5, and Debian

If running Debian testing/jessie as of Aug 2013, the First Stanza, above, may need to be changed from

       index /mythweb/mythweb.php;

to

       index mythweb.php;

If session data is not being saved (for example, if "Settings --> TV --> My Session" has blank date formats), apply the patches from "http://code.mythtv.org/trac/ticket/9833" and "http://code.mythtv.org/trac/ticket/11513".

See Also