Ticket #6721: 6721-mythweb-install-doc.diff

mythplugins/mythweb/INSTALL

@@ -2 +2 @@
 requirements and instructions for MythWeb.  Please see README for other
 information.
 
-October 26, 2008
+July 13, 2009
 
 ========
 Contents
@@ -17 +17 @@
 4.3         Webserver
 5.0     Apache
 5.1         Apache Config
+5.2         Apache Security Config
 6.0     Lighttpd
 7.0     PHP
 
@@ -41 +42 @@
     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
+(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:
 
@@ -50 +51 @@
     http://www.perl.com/
 
 Current versions of these in use by the MythWeb developer(s) are 2.2.x for
-Apache, 5.1.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
+Apache, 5.1.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 MySQL when building PHP.
 
 It is also possible to use MythWeb with Lighttpd (Lighty):
@@ -63 +64 @@
 ==========
 
 There are two official ways to download MythWeb.  You can either download it as
-part of the MythPlugins tarball from http://mythtv.org/ or you can grab it
+part of the MythPlugins tarball from http://www.mythtv.org/ or you can grab it
 directly from a subversion checkout, as described at http://svn.mythtv.org/trac
 
 Regardless of which method you end up choosing, you should be left with a
@@ -99 +100 @@
 
 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 an expert, we hope that you do not find
+you somewhere in between novice and expert, we hope that you do not find
 the following sections too boring, but please pay attention in case you
 overlook something important.
 
@@ -116 +117 @@
 
 The second most common situation would look something like this:
 
-    http://192.168.0.51/mythweb/
+    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 generally assume that your apache
-document root directory is:
+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.
+distribution has placed it somewhere else, e.g.:
 
     /home/www/htdocs
     /var/apache
     /var/www
     /var/www/htdocs
 
-For the purposes of illustration, we're going to use the imaginary /web/htdocs
-directory to refer to your installation directory.
+Once you figure out where your copy of Apache is looking for files, copy your
+MythWeb files into that directory:
 
-Once you figure out where your copy of apache is looking for files, copy your
-mythweb files into that directory:
-
     cd mythplugins/mythweb
-    cp -R * /web/htdocs/
+    cp -R * /var/www/html/
 
 ===============
 4.2 Permissions
@@ -151 +150 @@
 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 /web/htdocs/data
-    chmod g+rw /web/htdocs/data
+    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
+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.
+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 /web/htdocs/data
+    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.21, MythWeb contains configuration files for both Apache and Lighty. You
-will need to chose ONE of these files and install it in your webserver's
-configuration directory.  I will explain this later.
+As of 0.21, MythWeb contains configuration files for both Apache and Lighty.
+You will need to chose 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
+webserver, and then follow the instructions in the appropriate subsection:
 
     mythweb.conf.apache         (See section 5.0)
     mythweb.conf.lighttpd       (See section 6.0)
@@ -186 +199 @@
 5.0 Apache
 ==========
 
-MythWeb relies on two apache modules that are sometimes built in or
+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
+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
@@ -204 +217 @@
 
 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
@@ -215 +229 @@
 
 The directions below will have you set up MythWeb without any authentication
 at first, make sure you disconnect the machine from the network for these
-steps. For most this will work:
-  ifdown eth0
+steps.  For most this will work:
+
+    ifdown eth0
+
 But you can also just unplug the network cable temporarily.
 
 First, open mythweb.conf.apache in your favorite editor and look for what
 should be the first non-comment line in the file:
 
+    <Directory "/var/www/html/data" >
+
+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 <Directory> section is for the main MythWeb installation 
+directory:
+
     <Directory "/var/www/html" >
 
-You should change that path to match the document root directory you discovered
-in section 4.0, such that it might look something like:
+As before, you should change that path to match the directory that you installed
+MythWeb into (but this time to the MythWeb root directory).
 
-    <Directory "/web/htdocs" >
-
 Continue on in the file and find the following lines:
 
     setenv db_server        "localhost"
@@ -237 +261 @@
     setenv db_password      "mythtv"
 
 You should update these so that they match the settings required to connect to
-your MythTV master backend.
+your MythTV database server.
 
 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.
+Finally, you should put this file into Apache's "extra config files" directory.
 On Fedora, this is:
 
     /etc/httpd/conf.d/
@@ -254 +278 @@
     /etc/apache/conf.d/
     /etc/apache2/conf.enabled.d/
 
-Generally if there /etc/apache2/sites-available or similar directory you
-want to place this there and then run:
+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
 
@@ -264 +288 @@
 
     mv mythweb.conf.apache /etc/apache2/conf.d/mythweb.conf
 
-Then start/restart apache:
-  /etc/init.d/apache2 stop
-  /etc/init.d/apache2 start
-Or similar, this depends on the distribution.
+Then start/restart Apache with:
 
-Now you should be able to load mythweb. If you do not please review the
-mythweb.conf 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
+    /etc/init.d/apache2 start
 
-  /etc/init.d/apache2 stop
+(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
+    ifup eth0
 
-Or, plugging the network cable back in, depending on how you disabled it
-earlier. Now google for the error message you see at the end of:
+or by plugging the network cable back in, depending on how you disabled it
+earlier.  Now google for the error message you see at the end of:
 
-  tail /var/log/apache2/error.log
+    tail /var/log/apache2/error.log
 
-or similarly named error log for apache. Chances are someone else has
+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
 ==========================
@@ -296 +327 @@
 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
+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
+    htdigest -c /etc/mythweb.password.digest MythTV username
 
 And this for each additional user:
-  htdigest /etc/mythweb.password.digest MythTV username
 
+    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
+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.
+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.
+The next step is to reload Apache so it can use the new configuration:
 
-Now when you access the mythweb pages it should prompt you for a username
-and password. Type these in and make sure things work.
+    /etc/init.d/apache2 stop
+    /etc/init.d/apache2 start
 
-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.
+(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
 ============
@@ -334 +367 @@
 =======
 
 PHP tries to determine the system's local timezone settings automatically
-but may not be successful on every distribution. To ensure that PHP uses
+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
+    vim /etc/php.ini
 
 add/uncomment the date.timezone variable:
 
-  date.timezone = Europe/London
+    date.timezone = Europe/London
 
 and then restart Apache (exact commands depend on distribution):
 
-  /etc/init.d/apache2 stop
-  /etc/init.d/apache2 start
-
+    /etc/init.d/apache2 stop
+    /etc/init.d/apache2 start