This is the INSTALL file for the MythWeb package. It contains the installation requirements and instructions for MythWeb. Please see README for other information. June 6, 2010 ======== Contents ======== 1.0 Requirements 2.0 Source 3.0 Experts 4.0 Everyone Else 4.1 Install Overview 4.2 Permissions 4.3 Webserver 5.0 Apache 5.1 Apache Config 5.2 Apache Security Config 6.0 Lighttpd 7.0 nginx 8.0 PHP ======= Summary ======= PLEASE, PLEASE read this document. People seem to skip over this, under the mistaken assumption that MythWeb will just work with no configuration. While we've tried to make it as auto-detecting as possible, it usually still needs some hand-editing to account for variances in install preferences, etc. Please also read the FAQ in the README file, since it answers several common post-install questions/concerns. ================ 1.0 Requirements ================ First of all, you need MythTV, which you should be able to track down at: http://www.mythtv.org In addition to all the various things required to get MythTV up and running (which are documented in the main MythTV source), you need Apache, Perl and PHP up and running on either the same machine as MythTV, or one that is not blocked from communication by a firewall: http://www.apache.org http://www.php.net http://www.perl.com/ Current versions of these in use by the MythWeb developer(s) are 2.2.x for Apache, 5.3.x for PHP, and 5.8.x for Perl. Make sure to build both Apache and PHP according to the instructions at the PHP home site, and be sure to include support for session, MySQL, pcre, posix and json when building PHP. It is also possible to use MythWeb with Lighttpd (Lighty): http://www.lighttpd.net/ PHP Requirements: PHP Optionals: Sockets (UPnP Auto Discovery) ========== 2.0 Source ========== There are two official ways to download MythWeb. You can either download it as part of the MythPlugins tarball from http://www.mythtv.org/ or you can grab it directly from a git checkout, as described at http://code.mythtv.org/trac Regardless of which method you end up choosing, you should be left with a directory named mythweb, which contains mythweb.php, mythweb.pl and a handful of other files/directories (including this file). =========== 3.0 Experts =========== If you are not an expert, please skip to section 4.0. Experts, the following commands should be enough for you to figure out what's going on: cp -r mythweb/* /var/www/html/ vi /var/www/html/mythweb.conf.apache mv /var/www/html/mythweb.conf.apache /etc/httpd/conf.d/mythweb.conf /etc/init.d/httpd restart ================= 4.0 Everyone Else ================= If you are reading this section, we're going to assume that you have only minimal experience configuring both Linux and a webserver. For those of you somewhere in between novice and expert, we hope that you do not find the following sections too boring, but please pay attention to ensure that you don't overlook something important. ==================== 4.1 Install Overview ==================== Most people will be running their MythWeb installation on the same system that hosts the MythTV backend server, and will not be running any other web services, so we will be expecting that you will want to access your machine directly, like: http://192.168.0.50/ The second most common situation would look something like this: http://192.168.0.50/mythweb/ The differences between these situations are trivial, and if you cannot figure out how to do the second location from this guide, please don't hesitate to drop into #mythtv-users on irc.freenode.net to ask for help. For the purpose of this guide, we will assume that you want to access your machine directly (first situation above) and that your Apache document root directory is: /var/www/html This is not the case on every system, and you may find that your chosen distribution has placed it somewhere else, e.g.: /home/www/htdocs /var/apache /var/www /var/www/htdocs Once you figure out where your copy of Apache is looking for files, copy your MythWeb files into that directory: cd mythweb cp -R * /var/www/html/ =============== 4.2 Permissions =============== The next thing you need to do is make sure that your web server can write to MythWeb's data directory. This should be as simple as: chgrp -R apache /var/www/html/data chmod g+rw /var/www/html/data Please note that different distributions use a different userid for Apache (e.g. Ubuntu uses www-data). Please be aware that you may need to consult Apache's httpd.conf (often found at /etc/httpd/httpd.conf) file to verify which user/group Apache is set to run as. As a last resort, you can make the directory world-writable: chmod a+rw /var/www/html/data However, I strongly discourage this, since it is a slight security concern to give write permissions to any arbitrary user on your system. In order for MythWeb to display channel icons, they must exist in a directory that MythWeb can access. Many current distributions create user home directories with permissions of 700, which will stop MythWeb from being able to access icons located in a user's ~/.mythtv/channels directory. The location of each channel's icon is stored in the MythTV database. In order to resolve this issue, icons can be manually copied to MythWeb's data/tv_icons directory and chown'd to apache:apache. Another method to provide access to icons located within a user's home directory is to alter the permission of the home directory itself. Older distributions have used 0755 permissions, however this represents a large security risk as all other users on the system will have read access to that user's home directory, so it is not recommended. ============= 4.3 Webserver ============= As of 0.28, MythWeb contains configuration files for Apache, Lighty and nginx. You will need to choose ONE of these files and install it in your webserver's configuration directory. This will be explained later. The first thing you must do is find the configuration file for your chosen webserver, and then follow the instructions in the appropriate subsection: mythweb.conf.apache (See section 5.0) mythweb.conf.lighttpd (See section 6.0) mythweb.conf.nginx (See section 7.0) ========== 5.0 Apache ========== MythWeb relies on two Apache modules that are sometimes built in or enabled by default: mod_env mod_rewrite If you compiled Apache yourself, or are experiencing server trouble loading MythWeb, please make sure that these are enabled. There are also three documented sections in the conf file that are disabled by default, but I strongly recommend that you enable. They require: mod_deflate mod_headers mod_auth_digest To enable these on most systems "a2enmod" will work, for instance on Ubuntu you need to type these commands before MythWeb will work: a2enmod rewrite a2enmod deflate a2enmod headers a2enmod auth_digest The asx streaming feature requires cgi is enabled: a2enmod cgi ================= 5.1 Apache Config ================= The initial set of directions below will have you set up MythWeb without any authentication, so make sure you disconnect the machine from the network if you are in a "hostile" environment. However, if you are configuring your system behind a firewall in a home deployment, it may not be required. You can disable your ethernet interface by typing: ifdown eth0 But you can also just temporarily unplug the network cable. First, open mythweb.conf.apache in your favorite editor and look for what should be the first non-comment line in the file: You should change that path to match MythWeb's data directory. It is a subdirectory within the directory you copied the MythWeb files to above in section 4.1. The purpose of this Directory section is to place specific restrictions on MythWeb's data directory. The following section is for the main MythWeb installation directory: As before, you should change that path to match the directory that you installed MythWeb into (but this time to the MythWeb root directory). Continue on in the file and find the following lines: setenv db_server "localhost" setenv db_name "mythconverg" setenv db_login "mythtv" setenv db_password "mythtv" You should update these so that they match the settings required to connect to your MythTV database server. If you have multiple lineups, or have a single lineup with more than 100 channels, you need to increase the amount of memory that PHP is allowed to use as it processes various commands. Look for "php_value memory_limit" and increase it. In this example, with with 554 channels in the lineup, the memory limit had to be increased to allow searches to complete. # If you have a large number of channels, you may need to increase # this # value to prevent PHP from running out of memory. php_value memory_limit 512M By default, php is configured to prevent scripts from running for more that 30 seconds. This may not be long enough if you have complex queries, or many channels in your lineup, so increase the php_value max_execution_time 30 parameter. There are other settings in this file, too, which should be fairly well documented. Please read through the comments in the file itself to see if you can benefit from features that are disabled by default, or settings required for some of the more exotic installation possibilities. Finally, you should put this file into Apache's "extra config files" directory. On Fedora, this is: /etc/httpd/conf.d/ Other distributions might use something like: /etc/apache/conf.d/ /etc/apache2/conf.enabled.d/ Generally if a /etc/apache2/sites-available or similar directory exists you will want to place this file there and then run: a2ensite mythweb.conf You will have to figure out the correct path on your own, but once you do, move the MythWeb config file into place like so: mv mythweb.conf.apache /etc/apache2/conf.d/mythweb.conf Then start/restart Apache with: /etc/init.d/apache2 stop /etc/init.d/apache2 start (or similar, this depends on the distribution). At this stage, you should be able to open MythWeb in a browser on the machine on which you installed it by opening http://192.168.0.50/ If MythWeb does not load or you receive an error, please review the settings in the mythweb.conf file, the MythWeb README file, and this document for any potential mistakes you may have made. Please read the next section before re-enabling the network. If you still can't get it to work, disable Apache, using something like: /etc/init.d/apache2 stop Then re-enable the network using: ifup eth0 or by plugging the network cable back in, depending on how you disabled it earlier. Perform a web search (Google, etc) for the error message you see at the end of: tail /var/log/apache2/error.log or similarly named error log for Apache. Chances are someone else has had the same problem before and found a solution. ========================== 5.2 Apache Security Config ========================== The next step is to make sure everyone in the world can't take over your machine and that web crawlers don't automatically delete all your recordings. In the mythweb.conf file there is an authentication section. For this to work you will need to run this for the first user: htdigest -c /etc/mythweb.password.digest MythTV username And this for each additional user: htdigest /etc/mythweb.password.digest MythTV username Uncomment all the directives in this section of the file and change /var/www/htdigest to /etc/mythweb.password.digest or whatever else you want to call the password file. Do not place the file anywhere below /var/www or it will be world accessible. /var/www/htdigest would be the absolute worst name to use, since it appears in the MythWeb documentation which the bad guys read for easy breakins. The next step is to reload Apache so it can use the new configuration: /etc/init.d/apache2 stop /etc/init.d/apache2 start (or similar, this depends on the distribution). Now when you access the MythWeb pages, it should prompt you for a username and a password. Type these in and make sure things work. OK, if you reached this step you are almost done! Just plug in the network cable or type "ifup eth0" if you used "ifdown eth0" to disable the network earlier. ============ 6.0 Lighttpd ============ Configuring lighttpd for mythweb is straightforward and easy. 1. Copy the lighttpd config template file from your mythweb sources to your lighttpd configuration directory: # cp -vi ./mythweb.conf.lighttpd /etc/lighttpd/mythweb.conf.lighttpd Be sure to edit it for any particulars of your setup. 2. Edit your main lighttpd.conf file and add an include (with any path adjustments, depending on where you stored it): include "/etc/lighttpd/mythweb.conf.lighttpd" 3. For HTTP Digest authentication, create the credentials file (see the htdigest documentation for more detail): # htdigest -c /etc/lighttpd/mythweb.htdigest 'Authorized MythWebbers' tom 4. Set up a hostname that begins with "mythweb", pointing to an IP on which your lighttpd server is listening. 4a. For DNS: If you run your own DNS, add an "A" record for mythweb.whatever. 4b. For /etc/hosts: On all of your client browser machines, add something like the following to /etc/hosts: 192.186.0.3 mythweb.local mythweb Be sure to substitute the IP address at which lighttpd is reachable, of course. Also, take note that some systems are particular about the whitespace between the IP address and the hostname in /etc/hosts -- sometimes it must consist of tab (^H) characters. Then... Restart lighttpd and go! Assuming you set it up this way, simply direct your browser to http://mythweb.local/ and enjoy. ========= 7.0 nginx ========= Configuring nginx for mythweb. 1. Copy the nginx config example to your nginx configuration directory # cp mythweb.conf.nginx /etc/nginx/sites-available/mythweb Edit for any specifics of your setup. 2. For HTTP Basic Auth (nginx does not support HTTP Digest by default), create the credentials with htpasswd. # htpasswd -c /etc/nginx/mythweb.passwd mythweb 3. Make sure php-fpm is installed and running. # apt-get install php5-fpm 4. Restart nginx You should be able to access mythweb at the root of the hostname you defined (ex: https://localhost OR https://myth.mydomain.com) ======= 8.0 PHP ======= PHP tries to determine the system's local timezone settings automatically but may not be successful on every distribution. To ensure that PHP uses the correct timezone, edit php.ini and configure the date.timezone variable to your local timezone. For example, to set the PHP timezone to Europe/London: vim /etc/php.ini add/uncomment the date.timezone variable: date.timezone = Europe/London and then restart Apache (exact commands depend on distribution): /etc/init.d/apache2 stop /etc/init.d/apache2 start