This is the README file for the MythWeb package.
February 6, 2005

Version: .17
(c) 2002-2005  Thor Sigvaldason <mythtv(a)lamedomainname(o)com>
               Isaac Richards   <ijr(a)po(o)cwru(o)edu>
               Chris Petersen   <mythweb(a)forevermore(o)net>

with contributions from many people including:

Michael Kedl   <kedlm(a)knology(o)net>
Jonathan Kolb  <jkolb(a)greyshift(o)net
Ed Wildgoose   <edward(o)wildgoose(a)frmhedge(o)com>
Kenneth Aafloy <ke-aa(a)frisurf(o)no>

MythWeb is distributed under the GNU GENERAL PUBLIC LICENSE version 2
(see http://www.gnu.org)


Contents
========


1.0    About
2.0    Installation
3.0    FAQs
4.0    Plans/TODO
5.0    Submitting Patches


1.0 About
=========

    MythWeb is a set of php files intended (note the use future tense)
to let you access your listings, flag shows for recording, delete
recordings, etc., from a web browser. At some point in the future, it may
allow you to play your recorded content (music and/or(?) video) across a
network. Then again, it may not.

    Note that MythWeb is totally insecure and makes no pretense of
including any security mechanisms of any sort. You should really only run it
on an isolated network or (at the very least) behind a well secured firewall.



2.0 Installation
================

    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
and php up and running on the same machine as MythTV:

        http://www.apache.org
        http://www.php.net

    Current versions of these in use by the MythWeb developer(s) are 2.0.40
for Apache and 4.2.2 for php.  Make sure to build both according to the
instructions at the php home site, and be sure to include support for MySQL
when building PHP.

    In order for the included .htaccess to work properly, you will need to
set apache's "AllowOverride" setting to "All" (or at least "Options") for
the root mythweb directory.  This directive lives within <Directory/> tags,
so make sure you're changing the setting for the correct directory.

    At least for the time being, you will also need to make sure that
"short open tags" are enabled in /etc/php.ini (or wherever your favorite
distro chooses to place it).

    Somewhere in or off your root directory for htdocs (/www/htdocs if
you followed the instuctions at php.net), you should copy all the files
included in this distribution. To make sure you get images subdirectory,
you should do something like:

    cp -r . /wwww/htdocs/myMythWebDirectory

    Next, you need to make sure that your web server can write to a couple of
directories.  This should be as simple as:  **

    chgrp -R apache /wwww/htdocs/myMythWebDirectory/{image_cache,php_sessions}
    chmod g+rw /wwww/htdocs/myMythWebDirectory/{image_cache,php_sessions}

    Finally, and THIS IS VERY VERY IMPORTANT, you should then edit the file
config/conf.php (instructions for what to set are included in the file).
That's it. Point your web browser at http://your_machine_name/your_mythweb_path/
What could be simpler?

    ** Some distributions run apache as "nobody/nogroup" so please be aware
       that you may need to consult your /etc/httpd/httpd.conf file to verify
       which user/group apache is set to run as.

    Did you read the THIS IS VERY VERY IMPORTANT note in the previous paragraph?
People seem to skip over the config file and for some reason assume that
mythweb will just work with no configuration.  While I've tried to make it
as auto-detecting as possible, it often still needs some hand-editing.

3.0 FAQs
========

Q: Why don't my sessions stick?  (often manifests as sorting issues or settings
    not storing properly)
A: Make sure the php_sessions directory has the proper permissions, and that
    apache's AllowOverride setting is correct, as detailed in INSTRUCTIONS
    above.  Check config/conf.php to make sure that the server_domain constant
    is set correctly so that cookies will work properly.

Q: Why is my browser trying to display the PHP code instead of the server
    executing it for me?
A: First, make sure that you have PHP enabled in your webserver settings.  Once
    you have made sure that this is the case, look at the .htaccess file
    included with mythweb and remove (or comment out) the lines that mention
    "zlib".  It seems that some installations don't like these settings in
    .htaccess.  If you wish to enable compression (I suggest you do, since it
    significantly speeds up page-load times), you can safely re-enable these
    settings in /etc/php.ini.

Q: I want to access mythweb from the rest of the internet.
    How do I make it more secure?
A: The main .htaccess file contains commented-out apache controls for enabling
    htpasswd password authentication.  If you uncomment these, and create
    /var/www/htpasswd (see `man htpasswd` for details on how to do this), you
    will have some rudimentary password protection.  Combine this with making
    your mythweb connect only via SSL (see your webserver documentation for
    details), and you will have mythweb as secure as you can get without some
    fancy firewall rules.

Q: I've changed my theme to one that doesn't have a "settings" section.  Help!
A: Access any of the mythweb files and include RESET_THEME=yes among the URL
    parameters (eg. http://my.mythweb.tld/settings.php?RESET_THEME=yes ).  This
    will reset your theme to Default, where you can readjust your settings as
    needed.

Q: I can't open the status link, and get an error about url_fopen, what's
    wrong?
A: Some distributions (gentoo in particular) disable the allow_url_fopen
    setting by default, and php ignores this setting in the included .htaccess
    file.  You will need to edit your /etc/php.ini file (or wherever it is in
    your distribution) and set the value of allow_url_fopen to On.

Q: I've fixed a bug (or added a feature), how do I submit my patch?
A: First, join the mythtv-dev mailing list.  Then create your patch against
    mythweb CVS with `cvs diff -u`, first having made sure that your code is
    indented with 4 spaces and not tabs.  Next, either email your patch to the
    mailing list, or if it is bigger than 40k or so, put it on a web page and
    send a URL to the mailing list.  Either way, please include a detailed
    description of your patch in the email.  Make sure that the email contains
    "mythweb" in the subject line, or I may not see it.  If you don't hear back
    from me right away, don't worry.  As long as you follow these instructions,
    I will at least get back to you one way or another -- eventually.

4.0 Plan/TODO
=============

-Add more settings (recording profiles, etc)
-Find a way to integrate nuvexport and/or mythtranscode
-Clean up the inteface.

There are also a couple of feature requests that I don't have the time or
knowhow to implement.  If you're interested in taking any of these on, please
contact me so we can work out any necessary details (and by all means
subscribe to mythtv-dev)

    gettext - Our current translation system is messy and IMHO ugly.  Would
        be really cool to have gettext support.

    Smarty templates - It's been suggested that we use smarty templates
        instead of the current custom solution.  I don't mind this idea,
        as long as themes will be easy to update.

5.0 Submitting Patches
======================

I'm always open to people submitting patches.  The best way to do this is to
merely submit them to the mythtv mailing list (dev is best, but I subscribe
to both lists), with the word "mythweb" in the subject line (if you don't, I
probably won't see it), and preferably also the word "[PATCH]".

Please create patches against the most recent version of CVS by doing
"cvs diff -u".  I can deal with other "diff -u" patches, but if there have
been any major changes in cvs (there occasionally are), I won't put much
effort into trying to make your patch work, so please just use cvs.
