|
|
| Line 2: |
Line 2: |
|
| |
|
| == Installing == | | == Installing == |
| === Step 1: Environment ===
| | Removed because these instructions are very out of date. Contact Chris Page for more information. |
| Before attempting to install Newsagent, ensure that your server meets the requirements listed under [[#Environment requirements|Environment requirements]] and that all the Perl modules listed under [[#Perl modules required|Perl modules required]] are installed.
| |
| | |
| === Step 2: CKEditor ===
| |
| Next download the "Full Package" version of the latest release of CKEditor from [http://ckeditor.com/download the CKEditor site]. For example:
| |
| <source lang="txt" style="edit-emacs">
| |
| 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
| |
| </source>
| |
| This will create a <code>ckeditor</code> directory in <code>/var/www/localhost</code>. 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!
| |
| <source lang="txt" style="edit-emacs">
| |
| 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 .
| |
| </source>
| |
| | |
| === 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 <code>basic_db.sql</code> file provided in the source. The following assumes that the new user and database are both called 'newsagent':
| |
| <source lang="txt" style="edit-emacs">
| |
| cd /var/www/localhost/newsagent/newsagent/config
| |
| mysql -u newsagent -p newsagent < basic_db.sql
| |
| </source>
| |
| If the database is on a remote system, be sure to specify the <code>-h</code> (hostand possibly <code>-P</code> 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:
| |
| <source lang="txt" style="edit-emacs">
| |
| cd /var/www/localhost/newsagent/newsagent/config
| |
| cp site.cfg.dist site.cfg
| |
| nano -w site.cfg
| |
| </source>
| |
| You will minimally need to edit the <code>database</code>, <code>username</code>, and <code>password</code> 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 <code>settings</code> table and ensure the values are set appropriately. Important settings you will need to change are:
| |
| | |
| {| class="wikitable sortable"
| |
| |-
| |
| ! 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 || <nowiki>your@email.address</nowiki> || 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 || <nowiki>your@email.address</nowiki> || 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 || <nowiki>https://server.url/newsagent/images</nowiki> || 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 || <nowiki>https://server.url/.../uom_logo.png</nowiki> || Location of the default logo to include in emails; this should be a 154x63 image, preferably served over https.
| |
| |-
| |
| | httphost || <nowiki>https://server.url/</nowiki> || The URL of the root of the server Newsagent is being served from.
| |
| |}
| |
| | |
| If you have installed Newsagent to a location other than <code>/var/www/localhost/newsagent/newsagent</code>, and you are going to use mod_perl<ref>Which you should really be using.</ref>, you will need to modify the <codE>use lib</code> paths at the start of <code>newsagent/supportfiles/startup.pl</code> 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 <code>FollowSymLinks</code> and <code>ExecCGI</code> 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 <code>AllowOverride All</code> 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:
| |
| <source lang="xml" style="edit-emacs">
| |
| 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>
| |
| </source>
| |
| 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:
| |
| | |
| <source lang="xml" style="edit-emacs">
| |
| 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>
| |
| </source>
| |
| Note that you will need to modify the .htaccess file in the Newsagent directory to make the system work:
| |
| <source lang="txt" style="edit-emacs">
| |
| RewriteBase /newsagent/
| |
| RewriteCond %{REQUEST_URI} !^/newsagent/(templates|media|docs|ckeditor|images|testing|index.cgi)
| |
| </source>
| |
| Should be modified to read
| |
| <source lang="txt" style="edit-emacs">
| |
| # disable the RewriteBase
| |
| #RewriteBase /newsagent/
| |
| RewriteCond %{REQUEST_URI} !^/(templates|media|docs|ckeditor|images|testing|index.cgi)
| |
| </source>
| |
| | |
| === 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 [http://www.tidyp.com/])
| |
| | |
| === 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
| |
| | |
|
| |
|
| {{:Newsagent/Navbox}} | | {{:Newsagent/Navbox}} |
Mbasscp2 [
