From School of CS Wiki
Jump to: navigation, search
Newsagent Logo.png
Author Chris Page
Contact Support
Repository github
Issue tracker github
OS Neutral (web based)
Will not work with IE8 or older
URL Newsagent


Step 1: Environment

Before attempting to install Newsagent, ensure that your server meets the requirements listed under Environment requirements and that all the Perl modules listed under Perl modules required are installed.

Step 2: CKEditor

Next download the "Full Package" version of the latest release of CKEditor from the CKEditor site. For example:

cd /var/www/localhost
wget ''

This will create a ckeditor directory in /var/www/localhost. Be sure to get the latest CKEditor package, rather than just reusing the URL above!

Step 3: Software and dependencies

Once the software environment is prepared, you need to clone all the required repositories and set up links. With the exception of the first two lines of the instructions, the paths used are not important and are given for example only; they keep the Newsagent resources together inside one directory to prevent clutter, but you can arrange them however works for you. If you use different paths, remember to adjust the instructions accordingly!

cd /var/www
git clone
mkdir /var/www/localhost/newsagent
cd /var/www/localhost/newsagent
git clone
git clone
git clone
git clone
cd /var/www/localhost/newsagent/newsagent/templates/default/js
ln -s ../../../../MultiSelect .
ln -s ../../../../ckeditor .
ln -s ../../../../mootools-datepicker/Source datepicker
ln -s ../../../../twitter-text/js/twitter-text.js .

Step 4: Database and configuration

Now you need to create a MySQL user, an empty database, and grant all privileges on that database to the new user. Once these have been created you can initialise the database using the basic_db.sql file provided in the source. The following assumes that the new user and database are both called 'newsagent':

cd /var/www/localhost/newsagent/newsagent/config
mysql -u newsagent -p newsagent < basic_db.sql

If the database is on a remote system, be sure to specify the -h (hostand possibly -P options as appropriate (I would advise against using a remote database, unless you can guarantee a reliable and very fast connection to it).

Once the database has been set up you will need to create a new config/site.cfg file containing the information Newsagent needs to communicate with the database:

cd /var/www/localhost/newsagent/newsagent/config
cp site.cfg.dist site.cfg
nano -w site.cfg

You will minimally need to edit the database, username, and password variables on lines 3-5. Note that, to operate correctly, Newsagent currently requires a connection to a 'user data' database to support notification handling; please ask if you need information about this.

The database is created with a number of default settings that you will need to change: inspect the contents of the settings table and ensure the values are set appropriately. Important settings you will need to change are:

Name Default Description
base /var/www/localhost/newsagent/newsagent The filessytem path to the newsagent directory. Must be an absolute path.
scriptpath' /newsagent The web path to the newsagent system, relative to the host. If newsagent is at the root of the site set this to /, otherwise give the web path to the directory containing newsagent here.
logfile If set, log messages are written to this file. Ensure it is outside the web tree, but is writable by the webserver user.
Core:envelope_address your@email.address The email address to use as the envelope sender on 'housekeeping' emails sent by Newsagent. This is not used for notification emails (the article author's email is used for those).
Core:admin_email your@email.address The email address to show in the From: of housekeeping emails.
Article:upload_image_path /var/www/path/to/newsagent/images The filesystem location that uploaded images should be saved to. Must be writeable by the webserver user, and currently must be web accessible.
Article:upload_image_url https://server.url/newsagent/images The URL of the image upload path.
RSS:editor your@email.addy (Your Email) The email address to show in the <managingEditor> element of published RSS feeds.
RSS:webmaster your@email.addy (Your Email) The email address to show in the <webMaster> element of published RSS feeds.
RSS:title Feed Title The text to show in the <title> element of published RSS feeds.
RSS:description The latest news and events The text to show in the <description> element of published RSS feeds.
Article:logo_img_url https://server.url/.../uom_logo.png Location of the default logo to include in emails; this should be a 154x63 image, preferably served over https.
httphost https://server.url/ The URL of the root of the server Newsagent is being served from.

If you have installed Newsagent to a location other than /var/www/localhost/newsagent/newsagent, and you are going to use mod_perl[1], you will need to modify the use lib paths at the start of newsagent/supportfiles/ so that the mod_perl startup script can locate the Newsagent modules.

Step 5: Webserver

Newsagent has only been tested and deployed with Apache 2.2.x - while it should work under any webserver capable of serving content generated by perl scripts (either using mod_perl compatible semantics, or CGI), no instructions are currently available for this.

Under Apache, you must ensure that the directory containing Newsagent has the FollowSymLinks and ExecCGI options enabled. Omitting the latter will prevent Newsagent from working completely, while omitting the former will prevent it from fetching and serving supporting javascript and stylesheet resources. It is also important to include AllowOverride All to allow the .htaccess files within the Newsagent tree to operate - if you can not (or do not wish to) do this, you will have to replicate the .htaccess-controlled behaviour in the Apache configuration directly.

Subdirectory deployment

The following is an example Apache configuration fragment suitable for use when deploying Newsagent in a subdirectory of a website. Note that you may also want to copy some of the example caching directives out of the .htaccess file for increased performance:

    Alias /newsagent "/var/www/localhost/newsagent/newsagent"
    <Directory "/var/www/localhost/newsagent/newsagent">
        AllowOverride All
        Options +FollowSymlinks -Indexes +ExecCGI
        Order allow,deny
        Allow from all

    Perlrequire /var/www/localhost/newsagent/newsagent/supportfiles/
    PerlModule Apache2::Reload
    PerlInitHandler Apache2::Reload

    <Location /newsagent/index.cgi>
        SetHandler perl-script
        PerlResponseHandler ModPerl::Registry
        PerlOptions +ParseHeaders

When deployed using the above settings, you should not need to modify the .htaccess files in the Newsagent directory.

Root reployment

When deploying Newsagent at the root of a website, you can use an Apache configuration fragment based around the following:

Listen 443

<VirtualHost _default_:443>
    DocumentRoot "/var/www/localhost/newsagent/newsagent"

    SSLEngine on
    SSLCertificateFile /path/to/certfile.crt
    SSLCertificateKeyFile /path/to/keyfile.key
    SSLCertificateChainFile /path/to/intermediate.crt

    SSLProtocol All -SSLv2 -SSLv3
    SSLHonorCipherOrder     on

    ErrorLog /var/log/apache2/newsagent_error_log
    CustomLog /var/log/apache2/newsagent_access_log combined

    <Directory "/var/www/localhost/newsagent/newsagent">
        AllowOverride All
        Options +FollowSymlinks -Indexes +ExecCGI
        Order allow,deny
        Allow from all

    Perlrequire /var/www/localhost/newsagent/newsagent/supportfiles/
    PerlModule Apache2::Reload
    PerlInitHandler Apache2::Reload

    <Location /index.cgi>
        SetHandler perl-script
        PerlResponseHandler ModPerl::Registry
        PerlOptions +ParseHeaders

Note that you will need to modify the .htaccess file in the Newsagent directory to make the system work:

RewriteBase /newsagent/
RewriteCond %{REQUEST_URI} !^/newsagent/(templates|media|docs|ckeditor|images|testing|index.cgi)

Should be modified to read

# disable the RewriteBase
#RewriteBase /newsagent/
RewriteCond %{REQUEST_URI} !^/(templates|media|docs|ckeditor|images|testing|index.cgi)

Step 6: Configure authentication

Step 7: Admin account

Step 8: Define feeds, recipients, etc


Where specified, version numbers are the minimum versions of packages that Newsagent has been tested with. Later versions should work provided no breaking changes have been made.

Environment requirements

  • Linux. Windows may work, but has not been tested.
  • MySQL 5.6. Some features are MySQL specific at this time.
  • Apache 2. mod_perl is optional but very strongly recommended. Other web servers may work, but have not been tested.
  • Perl 5.16 (note: most of Newsagent testing has been on Perl 5.18 and 5.20)
  • ImageMagick 6.9
  • TidyP (see [1])

Git projects required

Perl modules required

The following required modules are often found in Linux distro repositories and should be installed from there:

  • CGI (including CGI::Utils)
  • Class::Accessor
  • Class::Mix
  • Compress::Bzip2
  • Crypt::Random
  • Date-Calc
  • Datetime
  • DBI
  • Devel::StackTrace
  • Email::MIME
  • Email::Sender::Simple (in Email-Sender)
  • Email::Sender::Transport::SMTP (in Email-Sender)
  • Email::Sender::Transport::SMTP::Persistent (in Email-Sender)
  • Email::Valid
  • Expect (Only required if the Webperl::AuthMethod::SSH auth method is used)
  • File::Type
  • HTML::Entities (in HTML::Parser)
  • HTML::Scrubber
  • HTML::TokeParser::Simple
  • JSON
  • Net::LDAPS (perl-ldap) (Only required if the Webperl::AuthMethod::LDAP OR LDAPS auth methods are used)
  • Params::Classify
  • Proc::Daemon
  • Regexp::Common
  • Try::Tiny (installed with Email-Sender)
  • WWW::Mechanize
  • XML::Simple

The following are usually not in repositories and will need to be installed via CPAN if not in your distro's repository:

  • CSS::Inliner
  • Crypt::Eksblowfish::Bcrypt (Only required if the Webperl::AuthMethod::Database auth method is used)
  • CGI::Compress::Gzip
  • experimental
  • DateTime::Event::Cron
  • Email::MIME::CreateHTML
  • File::LibMagic
  • HTML::FormatText
  • HTML::Tidy (Requires tidyp from )
  • HTML::WikiConverter::Markdown
  • List::Flatten
  • Lingua::EN::Sentence
  • Net::Twitter::Lite (Must be v0.12006 or later)
  • Net::SSH::Expect (Only required if the Webperl::AuthMethod::SSH auth method is used)
  • WebService::Validator::HTML::W3C

  1. Which you should really be using.


  • gravatar Mbasscp2 [userbureaucratcomp23420editorhandbook-editlabhelpstaff-editsysopPHRhYmxlIGNsYXNzPSJ0d3BvcHVwIj48dHI+PHRkIGNsYXNzPSJ0d3BvcHVwLWVudHJ5dGl0bGUiPkdyb3Vwczo8L3RkPjx0ZD51c2VyPGJyIC8+YnVyZWF1Y3JhdDxiciAvPmNvbXAyMzQyMDxiciAvPmVkaXRvcjxiciAvPmhhbmRib29rLWVkaXQ8YnIgLz5sYWJoZWxwPGJyIC8+c3RhZmYtZWRpdDxiciAvPnN5c29wPGJyIC8+PC90ZD48L3RyPjwvdGFibGU+]