Newsagent/Installing
Newsagent | |
Author | Chris Page |
---|---|
Contact | Support |
Repository | github |
Issue tracker | github |
OS | Neutral (web based) Will not work with IE8 or older |
URL | Newsagent |
Navigation | |
|
Installing
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 'http://download.cksource.com/CKEditor/CKEditor/CKEditor%204.4.6/ckeditor_4.4.6_full.zip'
unzip ckeditor_4.4.6_full.zip
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 https://github.com/TheWatcher/webperl.git
mkdir /var/www/localhost/newsagent
cd /var/www/localhost/newsagent
git clone https://github.com/UoMCS/newsagent.git
git clone https://github.com/TheWatcher/MultiSelect.git
git clone https://github.com/TheWatcher/mootools-datepicker.git
git clone https://github.com/twitter/twitter-text.git
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/startup.pl
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
</Directory>
Perlrequire /var/www/localhost/newsagent/newsagent/supportfiles/startup.pl
PerlModule Apache2::Reload
PerlInitHandler Apache2::Reload
<Location /newsagent/index.cgi>
SetHandler perl-script
PerlResponseHandler ModPerl::Registry
PerlOptions +ParseHeaders
</Location>
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>
ServerName server.name.here
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
SSLCipherSuite ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA
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
</Directory>
Perlrequire /var/www/localhost/newsagent/newsagent/supportfiles/startup.pl
PerlModule Apache2::Reload
PerlInitHandler Apache2::Reload
<Location /index.cgi>
SetHandler perl-script
PerlResponseHandler ModPerl::Registry
PerlOptions +ParseHeaders
</Location>
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
Requirements
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
- https://github.com/UoMCS/newsagent.git
- https://github.com/TheWatcher/webperl.git
- https://github.com/TheWatcher/MultiSelect.git
- https://github.com/TheWatcher/mootools-datepicker.git
- https://github.com/twitter/twitter-text.git
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 http://tidyp.com/ )
- 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
|
- ↑ Which you should really be using.