1This is the INSTALL file for the MythWeb package. It contains the 2installation requirements and instructions for MythWeb. Please see README 3for other information. 4 5June 6, 2010 6 7======== 8Contents 9======== 10 111.0 Requirements 122.0 Source 133.0 Experts 144.0 Everyone Else 154.1 Install Overview 164.2 Permissions 174.3 Webserver 185.0 Apache 195.1 Apache Config 205.2 Apache Security Config 216.0 Lighttpd 227.0 nginx 238.0 PHP 24 25======= 26Summary 27======= 28 29PLEASE, PLEASE read this document. People seem to skip over this, under the 30mistaken assumption that MythWeb will just work with no configuration. 31While we've tried to make it as auto-detecting as possible, it usually still 32needs some hand-editing to account for variances in install preferences, 33etc. 34 35Please also read the FAQ in the README file, since it answers several common 36post-install questions/concerns. 37 38================ 391.0 Requirements 40================ 41 42First of all, you need MythTV, which you should be able to track down at: 43 44 http://www.mythtv.org 45 46In addition to all the various things required to get MythTV up and running 47(which are documented in the main MythTV source), you need Apache, Perl and 48PHP up and running on either the same machine as MythTV, or one that is not 49blocked from communication by a firewall: 50 51 http://www.apache.org 52 http://www.php.net 53 http://www.perl.com/ 54 55Current versions of these in use by the MythWeb developer(s) are 2.2.x for 56Apache, 5.3.x for PHP, and 5.8.x for Perl. Make sure to build both Apache 57and PHP according to the instructions at the PHP home site, and be sure to 58include support for session, MySQL, pcre, posix and json when building PHP. 59 60It is also possible to use MythWeb with Lighttpd (Lighty): 61 62 http://www.lighttpd.net/ 63 64PHP Requirements: 65 66 67PHP Optionals: 68Sockets (UPnP Auto Discovery) 69 70========== 712.0 Source 72========== 73 74There are two official ways to download MythWeb. You can either download it 75as part of the MythPlugins tarball from http://www.mythtv.org/ or you can 76grab it directly from a git checkout, as described at 77http://code.mythtv.org/trac 78 79Regardless of which method you end up choosing, you should be left with a 80directory named mythweb, which contains mythweb.php, mythweb.pl and a 81handful of other files/directories (including this file). 82 83=========== 843.0 Experts 85=========== 86 87If you are not an expert, please skip to section 4.0. Experts, the 88following commands should be enough for you to figure out what's going on: 89 90 cp -r mythweb/* /var/www/html/ 91 92 vi /var/www/html/mythweb.conf.apache 93 94 mv /var/www/html/mythweb.conf.apache /etc/httpd/conf.d/mythweb.conf 95 96 /etc/init.d/httpd restart 97 98================= 994.0 Everyone Else 100================= 101 102If you are reading this section, we're going to assume that you have only 103minimal experience configuring both Linux and a webserver. For those of you 104somewhere in between novice and expert, we hope that you do not find the 105following sections too boring, but please pay attention to ensure that you 106don't overlook something important. 107 108==================== 1094.1 Install Overview 110==================== 111 112Most people will be running their MythWeb installation on the same system 113that hosts the MythTV backend server, and will not be running any other web 114services, so we will be expecting that you will want to access your machine 115directly, like: 116 117 http://192.168.0.50/ 118 119The second most common situation would look something like this: 120 121 http://192.168.0.50/mythweb/ 122 123The differences between these situations are trivial, and if you cannot 124figure out how to do the second location from this guide, please don't 125hesitate to drop into #mythtv-users on irc.freenode.net to ask for help. 126 127For the purpose of this guide, we will assume that you want to access your 128machine directly (first situation above) and that your Apache document root 129directory is: 130 131 /var/www/html 132 133This is not the case on every system, and you may find that your chosen 134distribution has placed it somewhere else, e.g.: 135 136 /home/www/htdocs 137 /var/apache 138 /var/www 139 /var/www/htdocs 140 141Once you figure out where your copy of Apache is looking for files, copy your 142MythWeb files into that directory: 143 144 cd mythweb 145 cp -R * /var/www/html/ 146 147=============== 1484.2 Permissions 149=============== 150 151The next thing you need to do is make sure that your web server can write to 152MythWeb's data directory. This should be as simple as: 153 154 chgrp -R apache /var/www/html/data 155 chmod g+rw /var/www/html/data 156 157Please note that different distributions use a different userid for Apache 158(e.g. Ubuntu uses www-data). Please be aware that you may need to consult 159Apache's httpd.conf (often found at /etc/httpd/httpd.conf) file to verify 160which user/group Apache is set to run as. 161 162As a last resort, you can make the directory world-writable: 163 164 chmod a+rw /var/www/html/data 165 166However, I strongly discourage this, since it is a slight security concern 167to give write permissions to any arbitrary user on your system. 168 169In order for MythWeb to display channel icons, they must exist in a 170directory that MythWeb can access. Many current distributions create user 171home directories with permissions of 700, which will stop MythWeb from being 172able to access icons located in a user's ~/.mythtv/channels directory. The 173location of each channel's icon is stored in the MythTV database. 174 175In order to resolve this issue, icons can be manually copied to MythWeb's 176data/tv_icons directory and chown'd to apache:apache. Another method to 177provide access to icons located within a user's home directory is to alter 178the permission of the home directory itself. Older distributions have used 1790755 permissions, however this represents a large security risk as all other 180users on the system will have read access to that user's home directory, so 181it is not recommended. 182 183============= 1844.3 Webserver 185============= 186 187As of 0.28, MythWeb contains configuration files for Apache, Lighty and 188nginx. You will need to choose ONE of these files and install it in your 189webserver's configuration directory. This will be explained later. 190 191The first thing you must do is find the configuration file for your chosen 192webserver, and then follow the instructions in the appropriate subsection: 193 194 mythweb.conf.apache (See section 5.0) 195 mythweb.conf.lighttpd (See section 6.0) 196 mythweb.conf.nginx (See section 7.0) 197 198========== 1995.0 Apache 200========== 201 202MythWeb relies on two Apache modules that are sometimes built in or enabled 203by default: 204 205 mod_env 206 mod_rewrite 207 208If you compiled Apache yourself, or are experiencing server trouble loading 209MythWeb, please make sure that these are enabled. 210 211There are also three documented sections in the conf file that are disabled 212by default, but I strongly recommend that you enable. They require: 213 214 mod_deflate 215 mod_headers 216 mod_auth_digest 217 218To enable these on most systems "a2enmod" will work, for instance on Ubuntu 219you need to type these commands before MythWeb will work: 220 221 a2enmod rewrite 222 a2enmod deflate 223 a2enmod headers 224 a2enmod auth_digest 225 226The asx streaming feature requires cgi is enabled: 227 228 a2enmod cgi 229 230================= 2315.1 Apache Config 232================= 233 234The initial set of directions below will have you set up MythWeb without any 235authentication, so make sure you disconnect the machine from the network if 236you are in a "hostile" environment. However, if you are configuring your 237system behind a firewall in a home deployment, it may not be required. 238 239You can disable your ethernet interface by typing: 240 241 ifdown eth0 242 243But you can also just temporarily unplug the network cable. 244 245First, open mythweb.conf.apache in your favorite editor and look for what 246should be the first non-comment line in the file: 247 248 <Directory "/var/www/html/data" > 249 250You should change that path to match MythWeb's data directory. It is a 251subdirectory within the directory you copied the MythWeb files to above in 252section 4.1. The purpose of this Directory section is to place specific 253restrictions on MythWeb's data directory. 254 255The following <Directory> section is for the main MythWeb installation 256directory: 257 258 <Directory "/var/www/html" > 259 260As before, you should change that path to match the directory that you 261installed MythWeb into (but this time to the MythWeb root directory). 262 263Continue on in the file and find the following lines: 264 265 setenv db_server "localhost" 266 setenv db_name "mythconverg" 267 setenv db_login "mythtv" 268 setenv db_password "mythtv" 269 270You should update these so that they match the settings required to connect 271to your MythTV database server. 272 273If you have multiple lineups, or have a single lineup with more than 100 274channels, you need to increase the amount of memory that PHP is allowed to 275use as it processes various commands. Look for "php_value memory_limit" 276and increase it. In this example, with with 554 channels in the lineup, the 277memory limit had to be increased to allow searches to complete. 278 279 # If you have a large number of channels, you may need to increase 280 # this 281 # value to prevent PHP from running out of memory. 282 php_value memory_limit 512M 283 284By default, php is configured to prevent scripts from running for more that 28530 seconds. This may not be long enough if you have complex queries, or 286many channels in your lineup, so increase the 287 php_value max_execution_time 30 288 289parameter. 290 291There are other settings in this file, too, which should be fairly well 292documented. Please read through the comments in the file itself to see if 293you can benefit from features that are disabled by default, or settings 294required for some of the more exotic installation possibilities. 295 296Finally, you should put this file into Apache's "extra config files" 297directory. On Fedora, this is: 298 299 /etc/httpd/conf.d/ 300 301Other distributions might use something like: 302 303 /etc/apache/conf.d/ 304 /etc/apache2/conf.enabled.d/ 305 306Generally if a /etc/apache2/sites-available or similar directory exists you 307will want to place this file there and then run: 308 309 a2ensite mythweb.conf 310 311You will have to figure out the correct path on your own, but once you do, 312move the MythWeb config file into place like so: 313 314 mv mythweb.conf.apache /etc/apache2/conf.d/mythweb.conf 315 316Then start/restart Apache with: 317 318 /etc/init.d/apache2 stop 319 /etc/init.d/apache2 start 320 321(or similar, this depends on the distribution). 322 323At this stage, you should be able to open MythWeb in a browser on the 324machine on which you installed it by opening 325 326 http://192.168.0.50/ 327 328If MythWeb does not load or you receive an error, please review the settings 329in the mythweb.conf file, the MythWeb README file, and this document for any 330potential mistakes you may have made. Please read the next section before 331re-enabling the network. If you still can't get it to work, disable Apache, 332using something like: 333 334 /etc/init.d/apache2 stop 335 336Then re-enable the network using: 337 338 ifup eth0 339 340or by plugging the network cable back in, depending on how you disabled it 341earlier. Perform a web search (Google, etc) for the error message you see 342at the end of: 343 344 tail /var/log/apache2/error.log 345 346or similarly named error log for Apache. Chances are someone else has 347had the same problem before and found a solution. 348 349========================== 3505.2 Apache Security Config 351========================== 352 353The next step is to make sure everyone in the world can't take over your 354machine and that web crawlers don't automatically delete all your 355recordings. 356 357In the mythweb.conf file there is an authentication section. For this to 358work you will need to run this for the first user: 359 360 htdigest -c /etc/mythweb.password.digest MythTV username 361 362And this for each additional user: 363 364 htdigest /etc/mythweb.password.digest MythTV username 365 366Uncomment all the directives in this section of the file and change 367/var/www/htdigest to /etc/mythweb.password.digest or whatever else you want 368to call the password file. Do not place the file anywhere below /var/www or 369it will be world accessible. /var/www/htdigest would be the absolute worst 370name to use, since it appears in the MythWeb documentation which the bad 371guys read for easy breakins. 372 373The next step is to reload Apache so it can use the new configuration: 374 375 /etc/init.d/apache2 stop 376 /etc/init.d/apache2 start 377 378(or similar, this depends on the distribution). 379 380Now when you access the MythWeb pages, it should prompt you for a username 381and a password. Type these in and make sure things work. 382 383OK, if you reached this step you are almost done! Just plug in the network 384cable or type "ifup eth0" if you used "ifdown eth0" to disable the network 385earlier. 386 387============ 3886.0 Lighttpd 389============ 390 391Configuring lighttpd for mythweb is straightforward and easy. 392 3931. Copy the lighttpd config template file from your mythweb sources to your 394lighttpd configuration directory: 395 396# cp -vi ./mythweb.conf.lighttpd /etc/lighttpd/mythweb.conf.lighttpd 397 398Be sure to edit it for any particulars of your setup. 399 4002. Edit your main lighttpd.conf file and add an include (with any path 401adjustments, depending on where you stored it): 402 403include "/etc/lighttpd/mythweb.conf.lighttpd" 404 4053. For HTTP Digest authentication, create the credentials file (see the 406htdigest documentation for more detail): 407 408# htdigest -c /etc/lighttpd/mythweb.htdigest 'Authorized MythWebbers' tom 409 4104. Set up a hostname that begins with "mythweb", pointing to an IP on which 411your lighttpd server is listening. 412 4134a. For DNS: If you run your own DNS, add an "A" record for 414mythweb.whatever. 415 4164b. For /etc/hosts: On all of your client browser machines, add 417something like the following to /etc/hosts: 418 419192.186.0.3 mythweb.local mythweb 420 421Be sure to substitute the IP address at which lighttpd is reachable, of 422course. Also, take note that some systems are particular about the 423whitespace between the IP address and the hostname in /etc/hosts -- 424sometimes it must consist of tab (^H) characters. 425 426Then... Restart lighttpd and go! 427 428Assuming you set it up this way, simply direct your browser to 429http://mythweb.local/ and enjoy. 430 431========= 4327.0 nginx 433========= 434 435Configuring nginx for mythweb. 436 4371. Copy the nginx config example to your nginx configuration directory 438 439# cp mythweb.conf.nginx /etc/nginx/sites-available/mythweb 440 441Edit for any specifics of your setup. 442 4432. For HTTP Basic Auth (nginx does not support HTTP Digest by default), 444create the credentials with htpasswd. 445 446# htpasswd -c /etc/nginx/mythweb.passwd mythweb 447 4483. Make sure php-fpm is installed and running. 449 450# apt-get install php5-fpm 451 4524. Restart nginx 453 454You should be able to access mythweb at the root of the hostname you 455defined (ex: https://localhost OR https://myth.mydomain.com) 456 457 458======= 4598.0 PHP 460======= 461 462PHP tries to determine the system's local timezone settings automatically 463but may not be successful on every distribution. To ensure that PHP uses 464the correct timezone, edit php.ini and configure the date.timezone variable 465to your local timezone. 466 467For example, to set the PHP timezone to Europe/London: 468 469 vim /etc/php.ini 470 471add/uncomment the date.timezone variable: 472 473 date.timezone = Europe/London 474 475and then restart Apache (exact commands depend on distribution): 476 477 /etc/init.d/apache2 stop 478 /etc/init.d/apache2 start 479