remove bug fine for mika
[iron-blogger] / README
1 == Iron Blogger Setup Instructions ==
2
3 Author: Benjamin Mako Hill
4
5 Thanks to Tony Yet from Iron Blogger Guangzhou who acted as the "guinea
6 pig" and whose experience in the installation helped provide the impetus
7 for writing this documentation.
8
9 === Things You'll Need ===
10
11 - Wordpress blog, set up on some server that you have admin rights to.
12 - GNU Ledger (http://ledger-cli.org/)
13 - Python YAML
14 - A mailing list or mailing alias. Each week you will send an email with
15   the results and that email should go to all the participants. Iron
16   Blogger doesn't automatically email everybody but you can create an
17   list on librelist.org, Google Groups, or on your own system with GNU
18   Mailman (for example). I just use a simple Postfix email alias but
19   other folks do different things.
20 - Git (http://git-scm.com/)
21
22 You can install the dependencies on Debian or Ubuntu with:
23
24   apt-get install ledger python-yaml git
25
26 === Setting it up ===
27
28 Iron blogger runs in two places:
29
30 1. The server that hosts your installation of Wordpress and installation
31    of Planet.
32 2. The administrator's client systems where the administrator will run
33    the scripts from. On my system, this is just my laptop.
34
35 === 1. Setting up the server ===
36
37 First, you will need to set up a  Wordpress installation. You can
38 download one from: https://wordpress.org/
39
40 Please follow the instructions there on how to set one up. 
41
42 Once you have installed wordpress, you need to turn on XML-RPC. You can
43 do that by checking the box in the Settings -> Writing -> XML-RPC
44 setting in the Wordpress administrative interface.
45
46 ==== Installing and setting up planet ====
47
48 Second, you need to install the Planet software which will show you an
49 aggregator of all of the blogs of people who are participating in a
50 single feed. Planet just sorts of regenerates from a "cronjob"
51 periodically.
52
53 You can put Planet anywhere, but I put it in a subdirectory of my
54 Wordpress directory. My wordpress site is set up to be
55 http://iron-blogger.mako.cc so planet will show up as
56 http://iron-blogger.mako.cc/planet
57
58 You can download the latest version of the planet code from:
59
60   http://www.planetplanet.org/
61
62 The will will be something like "planet-2.0.tar.bz2" and you can upack
63 it with "tar -jxvf FILENAME".
64
65 The key file in planet is a file called "config.ini". You will see that
66 the Iron Blogger client code will generate this automatically so don't
67 edit this file by hand
68
69 You will need to create an output directory and a templates directory. I
70 do this just by copying the examples directory with a command like: cp
71 -R examples/output out; cp -R examples templates; cp
72 examples/fancy/index.html.tmpl templates
73
74 Planet updates automatically. What I did was create a little shell
75 scripts with the following content (I created it in
76 "~/bin/update_planet.sh", but make sure you do "chmod +x" to make it
77 executable). Also make sure that you change the location (e.g.,
78 "/var/www/iron-blogger/planet") to the full path of your planet
79 installation on your server:
80
81   #!/bin/sh
82   cd /var/www/iron-blogger/planet
83   python ./planet.py ./config.ini 2>/dev/null
84
85 I then added a cronjob so that it runs every half hour. Make sure your
86 user is part of the crontab group or add them with "sudo adduser tony23
87 crontab". Once your userhas permission, you can type crontab -e and then
88 add the following line which will cause planet to update on the 14th and
89 44th minute of every hour:
90
91   14,44 * * * *   /home/mako/bin/update_planet.sh
92
93 Once planet is running, it will be at 'WORDPRESS_LOCATION/planet/out'
94 (replacing WORDPRESS_LOCATION with where ever your copy of Wordpress
95 actually is.
96
97 If you want it to be at just "/planet" you need to add an Apache alias
98 to your Apache configuration file that is something like this (except
99 with your location in the second part):
100
101   Alias /planet /var/www/iron-blogger/planet/out/
102
103 === 2. Setting up the administrators client system ===
104
105 First, you'll need to clone the repository into some safe place on your system:
106
107   git clone git://projects.mako.cc/iron-blogger
108
109 Iron Blogger asssumes you are running bit and will even commit things to
110 your git repository for you in certain situations (e.g., when you run
111 the weekly updates). As you make these changes, it's a good idea to keep
112 committ things to git with "git commit -a" or something similar.
113
114 ==== Configuration Files ====
115
116 The following files are configuration files that you will need to blank
117 out and then customize completing for your system:
118
119 1. bloggers.yml
120
121 This file contains the list of the bloggers. Find an example of someone
122 and copy and paste. The "start" date should be the Monday of the first
123 week that the person is active.
124
125 The list can contain multiple blogs and feeds. Every user is introduced
126 with a little nickname which, in our system, is usually that person's
127 user id.
128
129 As you set it up, this only needs to be a single person.
130
131 2. email_list
132
133 This files doesn't "do" anything. I just use it as a list of the people
134 who are using the system. That said, I like to keep a separate list of
135 who is participating.
136
137 3. ledger
138
139 The ledger file is the file you will end up modifying quite a lot in
140 order to keep up with who owes what, who had paid what, how much you
141 have spent at meetups, etc. The way it works is like a basic ledger
142 program but its data is all stored in a text file.
143
144 If you have not used GNU Ledger before, figuring out exactly how it
145 works can be a little tricky. In order to modify the file, however, you
146 should only need copy and paste from my material. To start with, move
147 the existing ledger file (from Iron Blogger Boston) to a new file with a
148 commad like "mv ledger ledger.boston.example".
149
150 Now, create a new file, called "ledger" in that directory that contains
151 a little bit of test data for your installation. Unfortunately, if you
152 just give it an empty file with no debts, the software will not work.
153 So, add a fictional debt and a payment (one of *each*). Once things get
154 up and running, you can remove this, just by removing the basic lines
155 from the line.
156
157 An example of a fictional line would be as follows (although you'd want
158 to replace "mako" with the name of someone who is listed in your
159 bloggers.yml file):
160
161 2011-11-14 Week 1
162   User:andresmh    -5
163   Pool:Owed:mako
164 2011-11-14 Payment
165   Pool:Owed:mako    -5
166   Pool:Paid
167
168 In a ledger, money must always come from where and go somewhere. There
169 are two entries in there.
170
171 The first entry is a debt: money is going from the User:mako account
172 into the Pool:Owed:mako account. As a result, User:mako is now at "$-5"
173 while the Pool:Owed is now positive $5.
174
175 The second entry is a payment: money is going from the Pool:Owed:mako
176 account into the Pool:Paid account. Think of it this way. In the first
177 bit, Mako owes the pools. After he pays, money is still in the pool, but
178 its in the part of the pool that has been paid up.
179
180 The person who runs Iron Blogger is basically the bank. Everything in
181 Pool:Paid is money that you have been given. Anything in Pool:Owed is
182 money that people owed the pool but which you have not received yet.
183
184 Once you have this set up, you can test it by running the ledger command
185 which you hopefully installed earlier. Try running "ledger -f ledger
186 balance Pool:Owed" to find the balance owed. In this command, the first
187 ledger is the program GNU Ledger while the "-f ledger" tell is to read
188 the ledger file in the local directory as its input.
189
190 4. out/
191
192 The Iron Blogger code was a subdirectory called "out" where it will
193 store intermediary data as it works. Just do "mkdir out" in your main
194 directory on the client.
195
196 ==== Things you will need to modify ====
197
198 1.
199
200 These two files should be edited so that they contain details about your
201 name/administrator, email address, etc:
202
203 templates/config.ini
204 templates/email.txt 
205
206 2.
207
208 You must modify this line in the file "config.py" that it points to the
209 Monday that starts the week that your version of Iron Blogger is
210 starting:
211
212 START = datetime.datetime(2011, 10, 24, 6)
213
214 Also edit config.py to include details on your wordpress setup. Here are
215 my details that include the PAGE_ID of the participants page:
216
217 XMLRPC_ENDPOINT = 'http://iron-blogger.mako.cc/xmlrpc.php'
218 USER            = 'mako'
219 BLOG_ID         = 1
220 PAGE_ID         = 12
221
222 The file will automatically keep the page of participants up to date.
223 You can see the page on our system here:
224
225 http://iron-blogger.mako.cc/participants/
226
227 The XMLRPC_ENDPOINT should be just your Wordpress URL followed by
228 xmlrpc.php. The USER should be your Wordpress user. The BLOG_ID should
229 be 1 and the PAGE_ID for the Parcipants page should be visible in your
230 Wordpress administrative interface.
231
232 5.
233
234 You'll also want to edit the "update-bloggers" script. You should only
235 need to change this line that copies the planet configuration over to
236 your server.
237
238   rsync $HERE/../iron-blogger-planet/config.ini epicenter:/var/www/iron-blogger/planet/
239
240 You will to change it so that the second part ("epicenter:/LOCATION")
241 points to your server in the way that you get to it with SSH (i.e., not
242 the web server location) and the full path to the directory on that
243 server where you have planet code setup. If you do not have rsync set
244 up, you should be able replace rsync with "scp" and have it work just
245 fine.
246
247 Once you've done this, you should be able to test this by typing
248 "./update-bloggers" in the terminal from your iron-blogger directory on
249 your client. If it's working correctly, it will ask you for a password
250 which will be your Wordpress password. The script will update the
251 participants page in Wordpress, generate a new "config.ini" file for
252 Planet, and copy it to your server.
253
254 === Adding bloggers and running weekly updates ===
255
256 To add a new blogger, you need to:
257
258 1. Edit "bloggers.yml' to add the metadata about the person
259 2. Run: ./scan-feeds.py
260 3. Run: "./update-bloggers" which will update the participants page and
261    the planet configuration.
262
263 When it's successful, it won't return anything.
264
265 Each week, you can run a weekly update. The updates don't happen
266 automatically which means the person running the system will need to do
267 it each week. If you miss a week, that's OK. You can run updates at any
268 time so, for example, you could run updates for the previous week, the
269 week before, and the week before that, all at the same time.
270
271 To run a weekly update, you need to:
272
273 1. Run ./scan-feeds.py
274 2. Run: ./weekly-update.py -n '2012-01-01'
275
276 The date, in quotes, should be the Monday that *starts* the week that
277 you are running it on. The "-n" in step 2 will mean to not make changes,
278 will not post to your iron-blogger website, and will not send out an
279 email. It will print out a list on the terminal.
280
281 If it all looks good, you can send it by running that command again with
282 step 3:
283
284 3. ./weekly-update.py '2012-01-01'
285
286 That command will ask for your Wordpress password again and will send
287 out an email to which ever address is in templates/email.txt. It will
288 show all the fines and will also commit the latest charges in the ledger
289 into git.
290
291 === Punting and Unpunting ===
292
293 By default, the code is set to "punt" people when they have a debt that
294 reaches $30 (or whatever 6 times the fine size (set by FINE_SIZE in
295 config.py). The weekly-update.py file will do this automatically. Their
296 debt dissappears. The idea is that people cannot just keep oweing more
297 and more. When people pay their $30, they are "unpunted" meaning that
298 they are back in the club.
299
300 Unpunting requires two changes:
301
302 1. Go to bloggers.yml and remove the line that says "end" associated
303    with the bloggers name.
304 2. Go to the ledger file and restore their debt (essentially, add $30
305    back into the Pool:Owed), and record their payment normally. The
306    following example shows how to do that:
307
308 2012-02-13 Unpunt
309   Pool:Owed:mako  30
310   User:mako
311 2012-02-13 Payment
312   Pool:Owed:mako    -30
313   Pool:Paid
314

Benjamin Mako Hill || Want to submit a patch?