The Scoop Content Management System can be used as a personal or group blog, or a community-edited discussion site, or any number of other things. It is powerful and flexible, and makes it surprisingly easy to add modular features, several of which are already available even if not included in the Scoop install.

This article provides brief instructions on installing Scoop, and an overview of its administration so you can see how things fit together and can start customizing your Scoop install.

Introduction

Scoop is getting a lot more attention lately, with several high profile, high traffic sites starting with or switching to Scoop. The original site, for which Scoop was written and which until very recently was the source of most of the useful features, is Kuro5hin.org, a popular general discussion site with the slogan "Technology and culture, from the trenches". A large site which recently switched to Scoop is the Daily Kos. The nature of its content (political) attracted a lot of traffic and a lot of commenters trying to start arguments, neither of which its previous engine was equipped to handle. Again in the political arena, Gen. Wesley Clark is using Scoop to power his campaign website in his bid to be the Democratic nominee for the upcoming US presidential race.

Scoop's design philosophy, and hence its core feature set, revolves around the idea of a completely community-driven discussion site. In the default setup, anybody with an account can submit articles, post comments on existing articles, and become a site editor by voting on whether or not submitted articles should be published. Articles can, in fact, be submitted, edited, published, and discussed with no intervention on the part of the site founder. Because the users decide what is "acceptable" as front page material, the flavour of the site can change over time as the users come and go. These features can be adjusted or even turned off entirely depending on how much editoral control or community involvement you, as a site administrator, want.

Installation Overview

To get Scoop up and running, you have to first install all the prerequisites, then configure Apache to use the Scoop code for your Scoop site's URL. The full details are below.

In short, you need Perl, MySQL, expat, Apache with mod_perl, and a whole pile of perl modules available from CPAN. Scoop comes with an install script (in the scripts/ directory) that tries to install the perl modules, collects information about your setup, then creates the database and a file with the Apache configuration Scoop requires. The install script assumes all of the other prerequisites are already correctly installed. The Apache configuration file the install script creates is not a full configuration file; it must be included in a working full Apache configuration file.

Once the prerequisites are installed, the database is created, and Apache is configured, Scoop is installed.

The most common problems encountered when installing Scoop are either due to buggy CPAN test suites on some of the perl modules, or due to not reading the install documentation fully. (The perl modules that typically cause trouble are listed in the install documentation, with explanations and workarounds.)

Installation Detail

The installation instructions below make several assumptions about the system you're installing Scoop on. If some of these assumptions don't apply to you, you can probably still install Scoop but may need some customized configuration or different instructions for a few of the steps.

The primary assumptions are that you are running linux (or BSD or other unix with similar tools available), either have no website or only a plain-html website on your server already, and are familiar with the general procedures for installing programs on linux. Scoop has been run on Windows and Mac OS X, and will co-exist happily with other dynamic content, but the setup is more complicated than what is described below.

The order of installation is quite conveniently also the order of ease. The easiest three prerequisites to install should be the first three installed: Perl, MySQL, and expat, an XML parser. In all three cases, if these programs are included as packages on your system install CD, simply install them with the default options. (For MySQL, you will also need the "mysql-dev" package.) They may already be installed on your system and you will need to do nothing (Perl is often installed by default). If they are not on your install CD, downloading the programs and doing a default install according to each one's install instructions works very well.

<DIV class="sidebar" style="border: 1px solid black; float: right; width: 20em; padding: 9px; margin: 9px">

The Trouble with CPAN

By far the most frustrating part of installing Scoop is installing all of the Perl modules it depends on. A quick glance at the install documentation's list of required modules shows which ones consistently cause problems. Virtually all of the problems are due to buggy test suites, and if the tests fail CPAN won't install the module. When the module is fine and the tests are broken, this makes everything look bad.

Scoop's install script tries to install all of the required modules, and succeeds with most of them. The troublesome ones usually have to be installed by hand through the CPAN shell, and often "forced" to make CPAN ignore the failed tests and install it anyway. Keep in mind that if there are any errors other than ones from the test suites, you probably shouldn't force install it.

Start CPAN as root using the command perl -MCPAN -e shell. If you have never used CPAN before, it will ask for configuration info. For the most part, the defaults work well, however when it asks you if it should "Follow Prerequisites" make sure you choose "ask" - if you set it to automatically follow prerequisites, it will possibly upgrade your entire perl install to the very latest version, which you may not want.

If the modules still fail to install after a normal install Module::Name, check the error messages against the list of required modules and try the suggestions given in the Scoop documentation. In the majority of cases, all of the modules will install properly with those suggestions.
</DIV>

The "medium" difficulty prerequisite should be installed next: Apache with mod_perl. The package included on your system install disks almost never works, you have to compile it yourself. You should download the most recent 1.3.x Apache code and the corresponding most recent mod_perl 1.x code from an official mirror. While Scoop can be made to run with Apache 2.x, it is not stable and should not be done unless you intend to help port Scoop to mod_perl 2.x.

The commands below will result in a basic Apache install with mod_perl compiled in, which will work with Scoop quite well. (The backslash at the end of some of the lines should have no spaces or other characters ofter them and before the newline.) The 'x' in both Apache and mod_perl directory names must be replaced with the version number you are using.

$ cd apache_1.3.x
$ ./configure
$ cd ../mod_perl-1.x
$ perl Makefile.PL \
APACHE_PREFIX=/usr/local/apache \
APACHE_SRC=../apache_1.3.x \
DO_HTTPD=1 \
USE_APACI=1 \
EVERYTHING=1 \
APACI_ARGS='--enable-module=rewrite --enable-module=expires \
--enable-module=mime_magic --enable-module=speling'
$ make
% make install

You should make sure Apache and MySQL are in your startup scripts, and start Apache and MySQL at this point to make sure they're working properly

The most difficult prerequisite is all the CPAN modules Scoop uses. Scoop's install script (scripts/install.pl) will try to install them for you, but quite a few will fail. See the sidebar and the install documentation for workarounds and details. All listed modules must be installed before Scoop will start. The install script will list which ones failed; when they are all installed, you can let the script continue to the rest of the setup.

Now you have all the prerequisites installed, and can configure Scoop. The remainder of the install script will do most of the work for you. Note that Scoop does not have a "make; make install" step; it is a collection of perl modules that Apache must be configured to load. The Scoop tarball only needs to be expanded somewhere that Apache can read its lib/ directory, and not somewhere that can be accessed from outside.

The install script will ask you a lot of questions; each one has an explanation and an example of what type of input it's looking for. Once you've answered all of the questions, the script creates Scoop's database (MySQL is still running, right?) and a partial Apache configuration file that contains all of the configuration directives Scoop needs, but is not a complete Apache configuration file. It must be included in a full, working Apache configuration file, either by copying and pasting the entire contents into the end of httpd.conf or by using the Include directive at the end of httpd.conf to pull it in.

Starting it up

If Apache is running, it must be stopped completely, then started. If there are no error messages and Apache starts properly, you can visit the URL you gave the install script as your Scoop site's base URL, and you should see Scoop's front page with some introductory content. Make sure your browser accepts cookies, and log in with the administrator's username and password (which you specified in the install script).

When you're logged in, the login form is replaced with a menu, but everything else stays the same. The links at the top (News, Diaries, etc) are to the section pages, one of the ways of categorizing stories and articles on your site. The left-hand sidebar has some introductory information about Scoop and where to get help. This can be removed or replaced with other content, but before you do so, make a note of the important information on it, such as where to go for help or advice. The centre column has a welcome article, and shows the format used to display stories. This is the part of your site that will change the most, as stories are submitted and published. The right sidebar contains the user and admin menus, and is where you start when customizing your site.

The user menu is seen by all logged-in users, and contains the types of things users will typically do on a Scoop site. The admin tools menu, just below that, contains links to all of the administration pages. Each link takes you to the controls for a different aspect of the site; as a new Scoop administrator, the ones you will be the most interested in are Site Controls, Blocks, Boxes, and Special Pages.

Site Controls are Scoop's site-wide preferences, where you can turn entire subsystems on or off (like Ads or Subscriptions) and set things like the email address Scoop uses to send mail. Each control (or variable, or var) has a description associated with it explaining what it's for.

Blocks are used to build the display. At first they can be confusing, because it's not always clear which block is used where, but they allow you to quickly and easily change the entire layout of the site. This is where all layout changes are made; there are no HTML template files to modify. (The html/ directory in the Scoop package contains the site's static files, such as its images and robots.txt.) Blocks can be inserted into other blocks by the simple method of putting the name of a block between vertical pipes (a key) where you want that block to appear. If you look at the block index_template, you'll see the main layout table and a few of these keys. Up near the top, you'll see |header| - and if you look at the block named header you'll see the HTML that is used to create the page header on every page. Fairly simple so far - but where Scoop's block system gets confusing is with the special keys, like |CONTENT|, which don't simply insert a block of the same name. Special keys are replaced with information from the database and sometimes other blocks, depending on what page is requested.

For example, on the front page (which uses index_template), the special key |CONTENT| is replaced with the newest stories published to the front page. The code that supplies the HTML inserted in |CONTENT| takes the block story_summary and fills all of its special keys with information about the story from the database, once for each story it displays.

The third kind of key you will see in index_template is a box key, and looks like |BOX,user_box| or |BOX,admin_tools|. These are replaced with the output of the box named in the key.

Boxes are bits of perl code that run every time they appear on a page. They range from very simple (the main_menu box which checks a few permissions and displays appropriate menu items) to very complex (the payment processing boxes used to handle ad and subscription payment and activation). Boxes have full access to all of Scoop's data and functions, as well as the normal Perl ability to call external programs and capture their output for parsing (the fortune_box is an example of this; it calls the unix program 'fortune' and displays the quote returned). There are a number of useful boxes not included with the default Scoop install available on the Scoop Box Exchange.

Special Pages are for primarily static content (such as an "about" or "FAQ" page) that you still want wrapped in the same header, footer, and sidebar menu as the more dynamic pages.

Once you've played with the above tools, you'll probably want to find out more about them and the other items in your admin tools menu. An excellent place to start is with the Scoop Admin Guide, which describes all of Scoop's features as well as giving a rundown of the admin tools menu and screens. For further help or advice if the documentation doesn't answer all of your questions, you can contact Scoop developers and other users through either the scoop-help mailing list or by visiting the #scoop channel on irc.slashnet.org.

Rhonda "janra" Hyslop has been using Scoop for three years, developing for a year and a half, and writing the documentation since spring 2003. She is a compulsive helper and her unofficial title is "the Scoop answer girl". She is also a part-time freelance writer and likes writing sci-tech articles on any bit of new research that makes her sit up and say "Ooh! that's *cool*..."

[Scoop | Rate and comment on Scoop]