A planet is a collection of posts from many different blogs, all somewhat related to one topic. It's a great way to keep tabs on a subject, a community, a technology, a team, a project or anything else that attracts a diverse range of bloggers.
Planeteria.org is a hosted planet reader. Planeteria allows anyone to make a planet, host it and administer it on Planeteria.org. After you make your planet, tell people about it. That's the whole point of community-building!
Planeteria was created by James Vasile (james at hackervisions dot net) in 2010 and has been maintained in his copious spare time since its creation.
Planeteria is run as a command line tool (planeteria.py) and two CGI scripts (admin.py and new_planet.py). The command line tool is used as follows:
Usage: planeteria.py [options]
Options:
- -h, --help show this help message and exit
- --force force downloading of cached upstream feeds
- --no-update prevent downloading of upstream feeds
- --delete-missing delete planets from db if they are not in file system
- --clean remove missing planets, unused feeds
The --clean flag doesn't remove old posts from the cache (just
unused feeds), and it doesn't delete unused planets, but in a future
version, it will.
This is a free open source project licensed under the AGPLv3 license.
This software was originally built on Venus. Venus is great if you're only running one planet, I highly recommend it. However trying to scale up the code for a single planet to make one system do many planets proved to be tricky, so those dependencies were discarded for more flexibility. The code is less robust as a result and could use some love.
In 2013, Aleta Dunne (aleta dot dunne at gmail dot com) took on fixing up the site as an internship project for the GNOME Outreach Program for Women (OPW). We always welcome more help, though!
Please let us know about bugs on the Github issue tracker, or submit a patch!
We have a roadmap in ROADMAP.md, please ping us if you want to tackle any of those!
There are some tests in the test directory. Run them from the main
directory with test/nose.sh . and you will see the start of some unit
testing. Please don't use the tests on a live, deployed install.
They create and destroy test planets.
The tests include tests of the web functionality. To run those tests,
you'll want to do be logged in as the same user that your apache
instance runs under (try sudo su www-data; bash). Otherwise, there
is a permissions mismatch when the user running the tests tries to
delete a file created by the web server and the 644 permissions
prevent it. If you get permission denied errors when running
nosetests, this might be the problem.
If you want to see the debug output while running nosetest, do tail -f log/planeteria.log in another screen or console.
Once you have complete coverage of everything except util.py, any uncovered functions in util.py can be moved to util_unused.
Planeteria is compatible with Python versions 2.3 - 2.7. For an
overview of its components, see doc/overview.dia.
git clone git://github.com/jvasile/Planeteria.git
Planeteria depends on several libraries. Follow the instructions for your OS below. We've only tested the installation on Debian and Mac OS X so far; we welcome any contributors who would like to help develop installation instructions for other operating systems.
We recommend installing these in a virtual environment (virtualenv) to
avoid conflicts with dependencies for other projects run on the same
machine. To learn more about installing and using virtualenv, go
to
http://www.virtualenv.org/en/latest/
get them all by typing (or pasting) the following into a terminal window:
aptitude install python-feedparser python-utidylib python-simplejson \
python-beautifulsoup python-lxml python-htmltmpl python-dateutil
Most packages can be installed on a Mac with pip, however one of
them needs to be downloaded before running pip. Go to
http://sourceforge.net/projects/htmltmpl/files/htmltmpl/
and download the 1.22 version (dated 2001-12-17).
WARNING: Do not click the link at the top of the page that says
"Looking for the latest version?" Although the version number seems
to be the correct version number, the link will actually download
htmltmpl 1.22 for PHP, not the Python version which is what this
project uses. The download should have the file name
htmltmpl-1.22.tar.gz; you should not see php in the
filename.
Once you have downloaded the htmltmpl tarball, note the file path for
the pip install. Copy and paste the following command into a terminal
window, and before you hit Enter, replace
path/to/htmltmpl-1.22.tar.gz with the file path on your system.
pip install feedparser pytidylib simplejson beautifulsoup lxml python-dateutil path/to/htmltmpl-1.22.tar.gz
The last step for Mac users is to install tidy, which is
required for
pytidylib
to work. We used Homebrew to
install tidy but it requires an extra step because it's not in the
default Homebrew repository. First, enter
brew tap homebrew/dupes
which tells homebrew to look in the dupes library, then:
brew install homebrew/dupes/tidy
which installs tidy.
Note that without running it on an Apache server, form submission won't work, so you won't be able to create or administer a planet, however you can view the static pages just fine.
Run planeteria.py which should generate the html files for the
site and place them in the /www folder. Then open
/www/index.html in a browser window.
The site requires sqlite3.
Make sure that the Planeteria directory is accessible by the web server (read/execute permission). You also need to give the server write permission for the following directories:
/data
/www
/log
For those setting up a virtual host on a Mac, this site walks you through the process in more detail than described below.
In your /etc/hosts file, add a new line underneath 127.0.0.1 localhost that says
127.0.0.1 planeteria.local
In your httpd.conf file, make sure it points to the /extra/httpd-vhosts.conf file like below. Verify the file path!
# Virtual hosts
Include /private/etc/apache2/extra/httpd-vhosts.conf
(The second line is commented out by default.)
In your /extra/httpd-vhosts.conf file, add the following settings:
<VirtualHost *:80>
ServerName planeteria.local (it should match the server name in your /etc/hosts file)
ServerAdmin [email protected]
DocumentRoot "/path/to/Planeteria/www"
ErrorLog ${APACHE_LOG_DIR}/planeteria-error.log
TransferLog ${APACHE_LOG_DIR}/planeteria-access.log
LogLevel debug
</VirtualHost>
<Directory "/path/to/Planeteria/www/">
Options +ExecCGI +FollowSymLinks
AllowOverride All
Order allow,deny
Allow from all
AddHandler cgi-script cgi py pl
</Directory>
Make sure to replace /path/to/Planeteria with the full file path to the location of the cloned Planeteria repo. Be especially attentive to the trailing slashes and quotation marks around the file paths, they may vary from machine to machine and can make the difference of whether the server can find the root directory or not.
Once your settings are saved, reboot the server and follow the directions above to load the site.
You need to tell Planeteria what domain and directory it lives in by
creating a data/base_href file with the domain. It must start
with http://. On the server which runs the site, that file
contains http://planeteria.org. On Aleta's virtual host, the
base_href file contains http://planeteria.local which just adds
http:// to the server name used in her /etc/hosts file.
In a sandbox environment, you can choose to generate the html files as
needed by running planeteria.py in the Terminal. However if you
want to deploy the site on a server to run on its own, you will need
to set up a cron job to run planeteria.py automatically every so
often. Planeteria.org runs it every 15 minutes.
To set this up, add a line like this to your crontab:
15 * * * * cd /path/to/Planeteria; ./planeteria.py
git log --pretty='format:%an'|sort|uniq -c|sort --reverse
457 James Vasile
3 jvasile
39 dtiburon
1 Wraithan (Chris McDonald)
1 Wacky Hacky
1 Sumana Harihareswara