== 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 'WORDPRESS_LOCATION/planet/out' (replacing WORDPRESS_LOCATION with where ever your copy of Wordpress actually is. 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