-------------------------------------
Scoop 0.9  (aka pre-1.0) 
by Rusty Foster <rusty@kuro5hin.org>

INSTALL:
$Revision: 1.41.2.1 $
$Date: 2002/10/12 05:00:47 $
$Author: panner $
--------------------------------------

-------------------------------
WARNING WARNING WARNING WARNING
-------------------------------
This is ALPHA software...

"...if it destroys your computer, rapes your pet, installs Win98 on your 
toaster and microwave, stops your pacemaker, causes sexual dysfunction, 
and turns your children into fucked-up trenchcoat-wearing teens carrying 
guns and worshipping Hitler, don't blame me because I told you it could 
do that and you went ahead and used it anyway."

--James Turinsky 
(http://projects.is.asu.edu/pipermail/slash-help/1999-October/000638.html)

Thanks for trying out Scoop, though, and please report anything 
interesting to us! See below for where to report problems or get help.

-------------------------
Installation Instructions
-------------------------

Easy way (try me first!): install.pl
====================================

There is now a Scoop installer!  Its located in scripts/install.pl
Give it a shot before you try the way below, which goes over doing it by 
hand.

Before you run the script, make sure that you have MySQL >= 3.22.x and
Perl >= 5.x installed.  Also make sure that you have apache and mod_perl 
working together.  If you don't already have apache and mod_perl playing
nice, then skip to the "Doing it by hand: Step 2" instructions for how
to install apache and mod_perl to work good.  NOTE: if you are running
apache and mod_perl rpm's, it might not work.  None of the developers have
had good luck with those, so you might want to recompile them and install
by hand.

So, make sure you're root, (or a root level account) and run the script with
./install.pl (from the scripts directory in the unpacked tarball).

The installer should detect most things for you, and will mostly just ask for
confirmation.  First it will try to install all of the modules for you using
CPAN. If you already have them installed, you can skip this step when it asks
If you've never used CPAN before it will try to configure itself first.
When it asks what policy to take when it finds dependencies, MAKE SURE you tell
it to ASK.  If you have it set to FOLLOW, it will probably try to upgrade perl
for you, which generally isn't what people want...

NOTE: For a list of all the modules Scoop needs, look below this section (under
step 1 of doing it yourself). Note that XML::Parser requires expat to be
installed, which you can get from http://sourceforge.net/projects/expat/. CPAN
cannot install this for you, and if it's not installed, then CPAN will not be
able to install XML::Parser.

Next it will configure your database for you.  If you already have a scoop
database installed, you can skip this step, or have it overwrite the previous
database, your choice.  You will need to know the root password for MySQL here.

Lastly, it will create a sample section of httpd.conf for you, by asking you 
a few questions and modifying the templates in the etc/ directory of your scoop
tarball.  

If it all went well, then you should have a httpd-<siteid>.conf file in the
directory you ran it from, and a working scoop database.  Just add a line to the
end of your apache httpd.conf similar to:
Include /path/to/httpd-siteid.conf

And shutdown and then start apache!  Its that simple!  (or should be ;-)

If for some reason this didn't work, please let us know how it didn't work, by
emailing scoop-help@lists.sourceforge.net with a description of the problem, the
OS you're using, apache/mod_perl versions, etc.  Or post a story to 
http://scoop.kuro5hin.org/

Once you've got it all working, you'll probably want to check out the "More fun
stuff" section near the end of this document for information on setting up
extra features.

================
Doing it by hand:
Step 1: Prepare your system
===========================

You need to have these programs installed:
	MySQL >= 3.22.x
	Perl >= 5.x

If you need Perl and MySQL, please install them now.  We'll be (re)installing
Apache along the way to be sure mod_perl is integrated properly.

We need to update Perl's configuration to ensure that all the required modules
that Scoop uses are present.  They can all be gotten from CPAN, and installed
in your preferred way.  I personally use MCPAN (perldoc CPAN), because it makes
things easy.  So, install the following libraries: 

(Note: I've appended some version numbers; these are not required versions, but
instead, versions that I've verified work on my system.  If you have problems,
I recommend you try these versions before giving up.)

    NAME                      VERSION (tested)

    Required:
    DBI                       1.21
    DBD::mysql                2.0414 (Note: or just 'Mysql', which is an older,
                                      but more stable, driver)
    Digest::MD5               2.20
    Apache::DBI               0.88
    Apache::Request           1.0
    Apache::Session           1.54
    Class::Singleton          1.03
    Crypt::UnixCrypt          1.0
    Mail::Sendmail            0.78
    String::Random            0.198
    Time::CTime               99.06_22_01
    Time::Timezone            101.062101
    XML::Parser               2.31 (Note: you need to install expat for this to
                                    install, http://sourceforge.net/projects/expat/
    LWP                       5.64
    Crypt::CBC                2.02
    Crypt::Blowfish           2.09
    XML::RSS                  0.97

As stated earlier, MCPAN is easiest to get this.  Another option for those of
you unsure about this 'CPAN' thing, is to run the installer, and just have it
run the cpan part for you.  Its the first thing it will try to do.  And after
it configures CPAN, just tell it you don't want it to configure the database
or apache for you.  Read the above section on install.pl for more information.


Step 2: Get Apache with mod_perl compiled
=========================================

Now we need to get Apache and mod_perl put together.

Grab the source files for them.  As of this writing, the best way to do this
is (be sure to replace the x in filenames with the correct version):

-- snip --
lynx --dump http://httpd.apache.org/dist/httpd/apache_1.3.xx.tar.gz > apache_1.3.xx.tar.gz
lynx --dump http://perl.apache.org/dist/mod_perl-1.xx.tar.gz > mod_perl-1.xx.tar.gz
-- snip --

Unpack apache and mod_perl (tar -zxf $file).

You should now have a dir structure similar to this:
/the/working/dir/
/the/working/dir/apache_1.3.xx/
/the/working/dir/mod_perl-1.xx/

Now you need to configure mod_perl.  cd into the mod_perl dir, and do this:

-- snip --
perl Makefile.PL \
	APACHE_PREFIX=/path/to/apache \
	APACHE_SRC=../apache-1.3.xx/src \
	DO_HTTPD=1 \
	USE_APACI=1 \
	EVERYTHING=1 \
	APACI_ARGS='--enable-module=rewrite --enable-module=expires --enable-module=mime_magic --enable-module=speling'
-- snip --

The APACI_ARGS there are given as an example.  It enables some handy
non-default Apache modules (rewrite for handy URL replacements, expires for
better cache friendlyness, mime-magic for proper MIMEs on files, and speling
to forgive small errors in the URL).  Change it to suit your needs.

Slackware users will want to have APACHE_PREFIX=/var/lib/apache and add 
--sbindir=/var/lib/apache/sbin to the APACI_ARGS to have it nicely integrate
into the default Slackware directory tree.

Then you 'make' and 'make install' .. viola!  You're almost done.

If this didn't work for you, there are even more detailed instructions on how
to do it in the doc/ dir of the Scoop distribution.

Step 3: Setup Scoop
===================

Now we have Perl with its modules, MySQL installed, and a nice mod_perl Apache 
complete with new program smell.  It's time for the final step, the setup of
Scoop.

Unzip the distribution tarball into a directory you want to serve 
web files from (like /home/httpd, /www, or /var/lib/apache/htdocs). 

Create a database for scoop.  The easiest way is to use the installer in the
script/ directory of the tarball.  Just run it from the script directory as
root, using ./install.pl . Tell it you don't want to configure cpan, but want
to continue on to the database configuration.  Then have it create a new
scoop database for you.

If you choose to do it by hand (or the installer fails), the following commands
should work, in your mysql command shell.  Words in <carats> may be replaced
with whatever makes you happy, within reason.  Defaults should work for most
people though, except <password> -- pick a real password!

mysql> create database <scoop>;

mysql> grant insert, update, delete, select on <scoop>.* to 
<nobody>@<localhost> identified by '<password>';

Note: the grant statement might have to be modified if you run MySQL 3.22.x

Then you'll need to dump the scoop.sql file into your new database.
From the command line, in the struct/ directory:
$ mysql -u root -p <scoop> < scoop.sql

Note:  that last '<' is a redirection operator, don't replace it with what makes
you happy! ;)

If you're doing a path-based install (http://www.yourdomain.org/scoop/), you'll
also need to set the path in the database.  If you made your database by hand
(instead of with install.pl), you'll need to set the path by hand as follows:

$ mysql -p <scoop>
[enter password]

mysql> update vars set value='/<path>' where name='rootdir';

Obviously, you need to make the <path> reflect your URL path (like '/scoop' --
do not add a trailing /!).

There are 4 more things you should change before your database is complete.
You can set these directly in mysql like above with 'rootdir'.  Assuming you 
logged into mysql as above,

mysql> update vars set value='your@email.address' where name='local_email';
mysql> update blocks set block='your@email.address' where bid='admin_alert';
mysql> update vars set value='http://your.site.address' where name='site_url';

Without setting local_email no one will be able to create an account.  Without
setting admin_alert no one will be alerted when people try to spam your scoop
site.  So don't forget! :-)

The logout_url is the url that people will be redirected to when they logout of
your site.  The site_url is what will show up in any links that your site emails
out to people (like new account confirmation emails).

With MySQL setup with the Scoop table and proper permissions, you need to set up
your httpd.conf.  First, decide if you're going to run as a virtual host
(http://scoop.yourdomain.org/), or a path-based install
(http://www.yourdomain.org/scoop/).  Open etc/httpd-vhost.conf in the first
case; etc/httpd-location.conf in the second.  Read the comments in those files
for what to edit, and what the values should be.

Once you've set all the stuff in whichever one you're using, copy the contents
of the file you edited into httpd.conf in your apache install, or include it with
Include /path/to/httpd-blah.conf
at the end of your apache httpd.conf

Step 4: Enjoy
=============

Start MySQL, start Apache, and try it out!

-----------------------------------
If you get it to run: :-)
-----------------------------------

If any of that helped, and you actually have it running (Bravo!)  then you'll
want to log in as "scoop" password "scoop" (unless you installed with the
installer, in which case log in as "scoop" with whatever password you created).
At this point, you'll want to read the html docs under scoop/docs.  I'm working
on making these useful, so feedback is appreciated.

If you did get it to work, email me at rusty@kuro5hin.org and let me know.
I'll be tickled.
( http://www.kuro5hin.org/?op=special;page=faq#kuro5hin ).

-------------------------------
If you can't get it to run: :-(
-------------------------------

There are a bunch of places to find support. First, look at: 
http://scoop.kuro5hin.org/

Our support mailing list info can be found at:
http://lists.sourceforge.net/lists/listinfo/scoop-help
Just sign up, and send it email describing the problem.

Most of the Scoop developers hang out in #scoop on irc.kuro5hin.org , and if
that happens to be empty, check out #kuro5hin on the same network.
Feel free to drop in and see if there are any knowledgeable people around.

If all else fails, or you need the kind of support that you're willing to pay 
for, you can contact me (Rusty) at rusty@kuro5hin.org.  I monitor all the 
locations just mentioned, so please make it a last resort. :-)

-------------------------------
More Fun Stuff
-------------------------------
For (nearly) complete docs on Scoop administration, see the Scoop Admin Guide,
available from the doc/ directory of your Scoop installation, or online at
http://guide.kuro5hin.org/.

Now that you've got Scoop running, you'll probably want to setup cron. See the
Scoop Admin Guide, section 3.14.3 for instructions on setting it up. Setting up
cron lets you use things like external (RSS-based) feeds, story digests, and
headline syndication.

Scoop now comes with a spellchecking capabilities, though you'll need to
install some more things to make it work (don't worry, it won't hurt). Grab
Aspell from http://aspell.net/, then get the Text::Aspell module from CPAN (or
you can get binaries of either or both of these). Then install them both, in
the same order, make sure everything checks out, and enable it in Scoop by
setting the spellcheck_enabled to true.

-------------------------------
Known Bugs and Issues
-------------------------------

* Cookies act funny sometimes, when you first set the system up.  If you can 
log in, but the next page reload logs you out, chances are you have a cookie 
problem.  Make sure you set $cookie_domain correctly, make sure you don't have 
old session cookies lying around, and turn on cookie notification to see if 
you're getting them at all.

A big factor in this is the number of periods in the name.  The seven special
top level domains are: "COM," "EDU," "NET," "ORG," "GOV," "MIL," and "INT."
These only require two (.kuro5hin.org works), but others (such as intranet.lan)
require three periods to be considered valid.  .web.intranet.lan will work where
.intranet.lan will fail.

* The documentation is only slowly getting better.  It may still be rough in
places. If you would like to contribute to the documentation as you learn scoop,
we'd love that.  Email hurstdog@kuro5hin.org for info on where we need help.

Thanks for using scoop!  I hope it works well and does exactly what you need.

-The Scoop developers


