README

   1 VJournal is a simple blog engine with extensive commenting feature.
   2 It's commenting style more or less mimics LiveJournal style blog sites,
   3 but it is designed to work on small sites with few blogs (or even just
   4 one)
   5
   6 It doesn't use any relational database, only Perl builtin dbmopen
   7 function (for information which shouldn't be directly shown to the
   8 users).
   9
  10 Blog (with discission) is kept in the static HTML files which are
  11 updated each time comment is posted. VJournal tries to limit number of
  12 files to be updated on each comment.
  13
  14 It updates just
  15
  16 1. Main file of the  post where comment is stored.
  17 2. Calendar files for month and
  18 3. day when post was posted, to update comment count
  19 4. Main page of the blog, if post is recent enough to be displayed.
  20
  21 VJournal doesn't keep user authentication information. It relies on
  22 OpenID to authenticate all users, including blog owner.
  23
  24 However, VJournal includes its own OpenID provider to autenticate blog
  25 owner. Blog owner is assumed to be a user, whose OpenID url is same as
  26 top-level URL of the blog, unless other OpenID url is specified as
  27 -owner option in the config.
  28
  29
  30 File structure of the blog:
  31
  32 Top level directory have index.html page which contain several recent
  33 posts, and set of directories with older posts by year and month:
  34
  35 In the top level directory there is .vjournalrc file which is just
  36 serialized perl hash for configuration options.
  37
  38 This hash should contain at least following options:
  39
  40 -owner - openid URL for blog owner
  41 -statedir - directory outside of public tree serverd by webserver, which
  42 contains following files:
  43         users.db - cached information about openid users
  44         session.db - information about user sessions
  45         owner.pwd - hash of owner password.
  46 Optionally, there also can be file openid.lst, which contain infomation
  47 about known openid sites. This information should be in the form
  48 site name:url_template.
  49
  50 There probably should be format specifier %s in the url_template, which would be
  51 substituted by user name. But some sites don't need this. For instance,
  52 google uses same url for all users.
  53
  54 Theoretically it is possible for several blogs to share same user cache
  55 and session cache (LiveJournal does so for millions of blogs), so
  56 owner.pwd can contain more than one record.
  57
  58 This file can be created using apache htpasswd utility (or simular)
  59 using blog URI (without protocol prefix) as user names.
  60
  61 It is recommended to deny HTTP  access to .vjournalrc, using web server
  62 access control, although filesystem permissions should allow this file
  63 be read by CGI process.
  64
  65 Inside publically accessable HTML tree should be subdirectories for the
  66 templates and user avatar pictures. By default these are subdirectories
  67 templats and avatars in the toplevel directory of blog.
  68 It can be redefined using options -templatedir and -avatardir in the
  69 config file.
  70
  71 If several blogs share user cache, they should share avatar directory
  72 too.
  73
  74 Initialization:
  75
  76 1. Install perl scripts and modules (once per all users)
  77 2. Create top level directory for blog, and put .vjournalrc there.
  78 Make directory writable to web server.
  79 3. Create empty avatar directory and make it writable to the webserver
  80 4. Create template directory and populate with templates.
  81 5. Create state directory and make it writable to webserver.
  82 6. Go to the /cgi-bin/post/urltop/, where urltop is top-level directory
  83 of your blog (may be it is just / if your entire site dedicated for
  84 blog). It is important to type into this url such path_info so webserver
  85 would put path of the directory with you .vjournalrc into
  86 PATH_TRANSLATED. You would be able to set owner password and upload your
  87 avatar.
  88
  89 Once you set up owner password, access to the post script would be
  90 resticted for blog owner.
  91