%= include 'footer'
__END__
=head1 NAME
rss.pl - Mojolicious based RSS news aggregator
=head1 SYNOPSIS
Single user, PostgreSQL backed, Mojolicious based RSS news aggregator
=head1 DESCRIPTION
This is a web based single user RSS news aggregator that was created after Google closed down Reader.
=head1 README
This is a web based RSS news aggregator designed for a single user. It uses Mojolicious as a web framework and PostgreSQL has its database. The interface is mobile friendly. It does not require any extra web server as it can be used with Mojolicious' hypnotoad web server. I currently run this script under OpenBSD 5.2 but there should be no problems with running it under Linux or other BSDs.
I used Google Reader quite a bit but when they closed it down I decided to write my own version. This is the result of that desire. I specifically wrote it for me and have not put any multi-user capability into the script.
When you first run the application it will create the necessary tables and their indexes if they do not exist.
=head1 USAGE
=head2 Main screen actions
=over 3
=item Update
Get the latest feeds by clicking Update
=item Favs
View your favorited items by click Favs
=item View
View the current RSS feeds by click View
=item Top
Go back to the top of a page be click Top at the bottom of the screen
=back
=head2 Viewing news for a feed
Click on the news name and the items for that feed will list
=head2 Options for reading and favoriting news items
If you want to mark all items of the feed being viewed as read then click All Read. If you want to only mark an individual news itam as read then click Read under the title of a news title. If you want to favorite a news item click Fav.
Once you get to the fifth news item and for each item there after you will have a link that says Top next to the news title. Click this to go back to the top of the page.
=head2 Manage Feeds
You access feed management by clicking the Manage link.
=over 3
=item Add Feed
Add feed names and URLs and then click Add Feed
=item Delete
To remove RSS feeds find the feed in the list and click its Delete button
=item Update
To update a RSS feeds URL find the feed in the list fill in the new URL and click the Update button
=back
=head1 CONFIGURATION
To use this script there are several items that need to be modified before the script can be used.
You will need to change the following areas at the top this of this script.
=head2 Example Database Creation
It is left to the reader to create the database and database owner as you may have specific configurations but this may give you some help. Yoy may need to su to the user of the PostgreSQL process in order to create the user.
=over 3
=item 1a. Create the database owner from the shell prompt
C<<< # createuser -P DBUSER >>>
=item 1b. Create the database owner from the psql prompt
C<<< psql> create user DBUSER with password 'DBPASS'; >>>
=item 2a. Create the database from the shell prompt
C<<< # createdb DBNAME -O DBUSER >>>
=item 2b. Create the database from the psql prompt
C<<< psql> create database DBNAME with owner DBUSER; >>>
=back
=head2 Network Access
You need to replace IPADDRESS:PORT with the address and port you want the server to listen
app->config(
hypnotoad => {
listen => ['http://IPADDRESS:PORT'],
}
);
=head2 Database Configuration
You also need to replace DBNAME, DBUSER, DBPASS with the relevant information for your PostgreSQL database
=over 3
=item my $pg_db = "DBNAME"; # database name
=item my $user = "DBUSER"; # database username
=item my $pass = "DBPASS"; # database user password
=back
=head1 RUNNING
Make sure the PostgreSQL database server is already running.
Once you have made the necessary configuration changes you will want to start this script like so:
C<<< # hypnotoad -f rss-1.0.pl >>>
Now point your browser to the IP address and port your configured.
When you start the application it will automatically create the table spaces and necessary indices.
=head1 PREREQUISITES
=over 1
=item PostgreSQL
=item Mojolicious::Lite
=item Mojo::UserAgent
=item HTML::FormatText
=item Time::Piece
=item Time::Seconds
=item Time::HiRes
=item XML::Feed
=item DateTime
=item DBI
=item utf8
=back
=head1 SCRIPT CATEGORIES
Web
=head1 AUTHOR
Mike Plemmons,
=head1 LICENSE
Copyright (c) 2014, Mike Plemmons
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of Mike Plemmons nor the
names of its contributors may be used to endorse or promote products
derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL MIKE PLEMMONS BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
=cut