added documentation

[iron-blogger] / README

== Iron Blogger Setup Instructions ==

Author: Benjamin Mako Hill

Thanks to Tony Yet from Iron Blogger Guangzhou who acted as the "guinea
pig" and whose experience in the installation helped provide the impetus
for writing this documentation.

=== Things You'll Need ===

- Wordpress blog, set up on some server that you have admin rights to.
- GNU Ledger (http://ledger-cli.org/)
- Python YAML
- A mailing list or mailing alias. Each week you will send an email with
  the results and that email should go to all the participants. Iron
  Blogger doesn't automatically email everybody but you can create an
  list on librelist.org, Google Groups, or on your own system with GNU
  Mailman (for example). I just use a simple Postfix email alias but
  other folks do different things.
- Git (http://git-scm.com/)

You can install the dependencies on Debian or Ubuntu with:

  apt-get install ledger python-yaml git

=== Setting it up ===

Iron blogger runs in two places:

1. The server that hosts your installation of Wordpress and installation
   of Planet.
2. The administrator's client systems where the administrator will run
   the scripts from. On my system, this is just my laptop.

=== 1. Setting up the server ===

First, you will need to set up a  Wordpress installation. You can
download one from: https://wordpress.org/

Please follow the instructions there on how to set one up. 

Once you have installed wordpress, you need to turn on XML-RPC. You can
do that by checking the box in the Settings -> Writing -> XML-RPC
setting in the Wordpress administrative interface.

==== Installing and setting up planet ====

Second, you need to install the Planet software which will show you an
aggregator of all of the blogs of people who are participating in a
single feed. Planet just sorts of regenerates from a "cronjob"
periodically.

You can put Planet anywhere, but I put it in a subdirectory of my
Wordpress directory. My wordpress site is set up to be
http://iron-blogger.mako.cc so planet will show up as
http://iron-blogger.mako.cc/planet

You can download the latest version of the planet code from:

  http://www.planetplanet.org/

The will will be something like "planet-2.0.tar.bz2" and you can upack
it with "tar -jxvf FILENAME".

The key file in planet is a file called "config.ini". You will see that
the Iron Blogger client code will generate this automatically so don't
edit this file by hand

You will need to create an output directory and a templates directory. I
do this just by copying the examples directory with a command like: cp
-R examples/output out; cp -R examples templates; cp
examples/fancy/index.html.tmpl templates

Planet updates automatically. What I did was create a little shell
scripts with the following content (I created it in
"~/bin/update_planet.sh", but make sure you do "chmod +x" to make it
executable). Also make sure that you change the location (e.g.,
"/var/www/iron-blogger/planet") to the full path of your planet
installation on your server:

  #!/bin/sh
  cd /var/www/iron-blogger/planet
  python ./planet.py ./config.ini 2>/dev/null

I then added a cronjob so that it runs every half hour. Make sure your
user is part of the crontab group or add them with "sudo adduser tony23
crontab". Once your userhas permission, you can type crontab -e and then
add the following line which will cause planet to update on the 14th and
44th minute of every hour:

  14,44 * * * *   /home/mako/bin/update_planet.sh

Once planet is running, it will be at WORD_PRESSLOCATION/planet/out.

If you want it to be at just "/planet" you need to add an Apache alias
to your Apache configuration file that is something like this (except
with your location in the second part):

  Alias /planet /var/www/iron-blogger/planet/out/

=== 2. Setting up the administrators client system ===

First, you'll need to clone the repository into some safe place on your system:

  git clone git://projects.mako.cc/iron-blogger

Iron Blogger asssumes you are running bit and will even commit things to
your git repository for you in certain situations (e.g., when you run
the weekly updates). As you make these changes, it's a good idea to keep
committ things to git with "git commit -a" or something similar.

==== Configuration Files ====

The following files are configuration files that you will need to blank
out and then customize completing for your system:

1. bloggers.yml

This file contains the list of the bloggers. Find an example of someone
and copy and paste. The "start" date should be the Monday of the first
week that the person is active.

The list can contain multiple blogs and feeds. Every user is introduced
with a little nickname which, in our system, is usually that person's
user id.

As you set it up, this only needs to be a single person.

2. email_list

This files doesn't "do" anything. I just use it as a list of the people
who are using the system. That said, I like to keep a separate list of
who is participating.

3. ledger

The ledger file is the file you will end up modifying quite a lot in
order to keep up with who owes what, who had paid what, how much you
have spent at meetups, etc. The way it works is like a basic ledger
program but its data is all stored in a text file.

If you have not used GNU Ledger before, figuring out exactly how it
works can be a little tricky. In order to modify the file, however, you
should only need copy and paste from my material. To start with, move
the existing ledger file (from Iron Blogger Boston) to a new file with a
commad like "mv ledger ledger.boston.example".

Now, create a new file, called "ledger" in that directory that contains
a little bit of test data for your installation. Unfortunately, if you
just give it an empty file with no debts, the software will not work.
So, add a fictional debt and a payment (one of *each*). Once things get
up and running, you can remove this, just by removing the basic lines
from the line.

An example of a fictional line would be as follows (although you'd want
to replace "mako" with the name of someone who is listed in your
bloggers.yml file):

2011-11-14 Week 1
  User:andresmh    -5
  Pool:Owed:mako
2011-11-14 Payment
  Pool:Owed:mako    -5
  Pool:Paid

In a ledger, money must always come from where and go somewhere. There
are two entries in there.

The first entry is a debt: money is going from the User:mako account
into the Pool:Owed:mako account. As a result, User:mako is now at "$-5"
while the Pool:Owed is now positive $5.

The second entry is a payment: money is going from the Pool:Owed:mako
account into the Pool:Paid account. Think of it this way. In the first
bit, Mako owes the pools. After he pays, money is still in the pool, but
its in the part of the pool that has been paid up.

The person who runs Iron Blogger is basically the bank. Everything in
Pool:Paid is money that you have been given. Anything in Pool:Owed is
money that people owed the pool but which you have not received yet.

Once you have this set up, you can test it by running the ledger command
which you hopefully installed earlier. Try running "ledger -f ledger
balance Pool:Owed" to find the balance owed. In this command, the first
ledger is the program GNU Ledger while the "-f ledger" tell is to read
the ledger file in the local directory as its input.

4. out/

The Iron Blogger code was a subdirectory called "out" where it will
store intermediary data as it works. Just do "mkdir out" in your main
directory on the client.

==== Things you will need to modify ====

1.

These two files should be edited so that they contain details about your
name/administrator, email address, etc:

templates/config.ini
templates/email.txt 

2.

You must modify this line in the file "config.py" that it points to the
Monday that starts the week that your version of Iron Blogger is
starting:

START = datetime.datetime(2011, 10, 24, 6)

Also edit config.py to include details on your wordpress setup. Here are
my details that include the PAGE_ID of the participants page:

XMLRPC_ENDPOINT = 'http://iron-blogger.mako.cc/xmlrpc.php'
USER            = 'mako'
BLOG_ID         = 1
PAGE_ID         = 12

The file will automatically keep the page of participants up to date.
You can see the page on our system here:

http://iron-blogger.mako.cc/participants/

The XMLRPC_ENDPOINT should be just your Wordpress URL followed by
xmlrpc.php. The USER should be your Wordpress user. The BLOG_ID should
be 1 and the PAGE_ID for the Parcipants page should be visible in your
Wordpress administrative interface.

5.

You'll also want to edit the "update-bloggers" script. You should only
need to change this line that copies the planet configuration over to
your server.

  rsync $HERE/../iron-blogger-planet/config.ini epicenter:/var/www/iron-blogger/planet/

You will to change it so that the second part ("epicenter:/LOCATION")
points to your server in the way that you get to it with SSH (i.e., not
the web server location) and the full path to the directory on that
server where you have planet code setup. If you do not have rsync set
up, you should be able replace rsync with "scp" and have it work just
fine.

Once you've done this, you should be able to test this by typing
"./update-bloggers" in the terminal from your iron-blogger directory on
your client. If it's working correctly, it will ask you for a password
which will be your Wordpress password. The script will update the
participants page in Wordpress, generate a new "config.ini" file for
Planet, and copy it to your server.

=== Adding bloggers and running weekly updates ===

To add a new blogger, you need to:

1. Edit "bloggers.yml' to add the metadata about the person
2. Run: ./scan-feeds.py
3. Run: "./update-bloggers" which will update the participants page and
   the planet configuration.

When it's successful, it won't return anything.

Each week, you can run a weekly update. The updates don't happen
automatically which means the person running the system will need to do
it each week. If you miss a week, that's OK. You can run updates at any
time so, for example, you could run updates for the previous week, the
week before, and the week before that, all at the same time.

To run a weekly update, you need to:

1. Run ./scan-feeds.py
2. Run: ./weekly-update.py -n '2012-01-01'

The date, in quotes, should be the Monday that *starts* the week that
you are running it on. The "-n" in step 2 will mean to not make changes,
will not post to your iron-blogger website, and will not send out an
email. It will print out a list on the terminal.

If it all looks good, you can send it by running that command again with
step 3:

3. ./weekly-update.py '2012-01-01'

That command will ask for your Wordpress password again and will send
out an email to which ever address is in templates/email.txt. It will
show all the fines and will also commit the latest charges in the ledger
into git.

=== Punting and Unpunting ===

By default, the code is set to "punt" people when they have a debt that
reaches $30 (or whatever 6 times the fine size (set by FINE_SIZE in
config.py). The weekly-update.py file will do this automatically. Their
debt dissappears. The idea is that people cannot just keep oweing more
and more. When people pay their $30, they are "unpunted" meaning that
they are back in the club.

Unpunting requires two changes:

1. Go to bloggers.yml and remove the line that says "end" associated
   with the bloggers name.
2. Go to the ledger file and restore their debt (essentially, add $30
   back into the Pool:Owed), and record their payment normally. The
   following example shows how to do that:

2012-02-13 Unpunt
  Pool:Owed:mako  30
  User:mako
2012-02-13 Payment
  Pool:Owed:mako    -30
  Pool:Paid