+=====+
                         ublog
                        +=====+

ublog is a minimal distributed multiuser blogging software (well ...
better: Perl hack) that is based on Git. ublog is Free Software and
distributed under the GNU GPL, version 2.0. What exactly does ublog
do? Well, ublog takes a plain-text blog config file (like blog.txt)
and automatically generates static html and rss files, in other words:
your blog. Try it out by typing: ./ublog blog.txt tmp/ . Then, the
example blog will be generated within the tmp/ folder. However, the
idea is that ublog is used in combination with Git. Your server runs
for instance a git server and a nginx webserver. You have a single repo
that only contains the blog.txt file, thus after each git push, your
server automatically runs ublog (via git server hooks), thus ublog
generated all necessary files for i.e., /var/www/htdocs/ of your nginx.

ublog via Git Benefits:

  + Distributed for e.g., a better censorship resistance (since you can
    push to multiple remotes and others can clone / pull your Git repo)
  + Secure, since all sites are static HTML
  + Fast, since all sites are static HTML
  + Minimal, since the blog does not run on some PHP, Ruby whatever crap
  + Backed up, since DVCS is used
  + Easy usage and setup, only a single blog text file
  + Can be used with multiple authors
  + RSS per author, tag and full RSS, tag cloud
  + Automatic content creation triggered on Git push

Blog entries are written in HTML or txt2html syntax, which you may check out
here: http://txt2html.sourceforge.net/ . Also, if you are using Debian, you
need to install txt2html with i.e., apt-get install txt2html

Blog text file layout:

Comments outside of blocks start with '#'. You need the following sections:

header = {
Here is your HTML body header in txt2html format.
}

footer = {
Here is your HTML body footer in txt2html format.
}

about = {
Here is your HTML about body in txt2html format.
}

settings = {
	title = My awesome blog
	entries_per_site = 20
	root_url = http://blog.mysite.org
	git_clone = git://git.mysite.org/blog.git    (optional)
	show_all_tags = 1                            (optional)
	use_txt2html = 0                             (optional, if 0: HTML used)
}

Then, there can be one or more authors, like:

author daniel = {
	name = Daniel Fubar
	show_nic = 0                                 (optional)
	email = daniel@mysite.org                    (optional)
	web = http://mysite.org                      (optional)
}

author jeff = {
	name = Jeff Fubar
	show_nic = 1                                 (this shows 'jeff' instead of 'Jeff Fubar')
	email = jeff@mysite.org
	web = http://mysite.org
}

...

The entry format is like 'entry <unix-timestamp> <author-nic> [<optional-tags>]' = ..., i.e.:

entry 1318878180 daniel [] = {
Entry text in txt2html.
}

entry 1318878180 jeff [photos] = {
Entry text in txt2html.
}

entry 1318878180 daniel [photos, iceland] = {
Entry text in txt2html.
}

The timestamp can be gathered via: date +%s . Note that two posts with the same
timestamp must not exist, since this is used as an index.

Furthermore, if you put a file named 'style.css' into your /var/www/htdocs (or
whatever root directory you are using for ublog), it will be used for the blog
as a style sheet.

Here's a rough description on what you need to do to setup ublog with Git:

  0. On your server: apt-get install txt2html, and copy ublog to /usr/bin/ublog
  1. Have git installed on your server, have i.e., 'git daemon &' running
  2. Plus a webserver, e.g. nginx with your default blog directory /var/www/htdocs/blog/
  3. Have a directory /pub/git/ where your Git repos are located at
  4. mkdir /pub/git/blog.git
  5. cd /pub/git/blog.git
  6. git init --bare
  7. touch /pub/git/blog.git/git-daemon-export-ok
  8. vim /pub/git/blog.git/hooks/post-receive
  9. Enter:  #!/bin/sh
             GIT_WORK_TREE=/tmp/blog/ git checkout -f
             ublog /tmp/blog/blog.txt /var/www/htdocs/blog/
     ... and mkdir /tmp/blog
 10. Check user and permissions of your repo, /var/www/htdocs/blog/ and
     /tmp/blog --> they should all match
 11. chmod a+x /pub/git/blog.git/hooks/post-receive
 12. Exit ssh of your server; on your client you clone the empty repo, like:
 13. git clone ssh://user@myserver.org/pub/git/blog.git
 14. Add the blog.txt example file of ublog and edit it to your needs
 15. Commit it and push it
 16. Now Git on your server says:
        local@box:~/blog$ git push origin master 
        user@myserver.org's password: 
        Counting objects: 5, done.
        Delta compression using up to 4 threads.
        Compressing objects: 100% (2/2), done.
        Writing objects: 100% (3/3), 291 bytes, done.
        Total 3 (delta 1), reused 0 (delta 0)
        remote: Parsing /tmp/blog/blog.txt blog ...
        remote: Checking ...
        remote: Generate html files in /var/www/htdocs/blog/ ...
        remote: Done!
        To ssh://user@myserver.org/pub/git/blog.git
            3f1c191..af2ce11  master -> master
 17. Now ublog has generated all of your blog html files
 18. Now you only need to make sure that nginx is configured correctly to view
     your blog online; on each push, ublog updates automatically your blog
 19. That's it. ;-)

Question, patches, and other stuff: borkmann@gnumaniacs.org