Getting Daizu up and running isn't particularly simple, unfortunately. These instructions should help though.
Installing the software
First download the latest Daizu source code and unpack it. You can then build it like this:
perl Build.PL ./Build
If you have appropriate permissions to install software globally then you can do this:
./Build install
Otherwise you can run the software directly from where you unpacked
it by running everything with perl -Ilib or adding the
lib directory to your PERL5LIB environment variable.
You can also run automatic tests on the code, by first editing the test.conf file which comes with Daizu and then running this:
./Build test
See the testing instructions for details about how the test suite works.
Creating the repository
You'll need a Subversion repository to store your content in, so do something like this:
svnadmin create web-repos svn co file:///home/geoff/web-repos web-content
Daizu requires there to be a trunk directory, and while you're making that you might as well make directories where you can put branches and tags if you ever need to use them. It is very important that the trunk be at the top level of the repository, and have that name.
cd web-content svn mkdir trunk branches tags svn ci
At this point you should probably get rid of the working copy, which is checked out at the top level of the repository, and check out the trunk. You'll usually be working in there.
svn co file:///home/geoff/web-repos/trunk web-content
Inside the trunk you can organize your content pretty much however you like, but I'd recommend creating a directory for each website you publish with Daizu. Create a top-level directory for your website even if there's only one of them, because if you ever decide to add a second website it might be a bit tricky to rearrange things.
A directory for a website should have two Subversion properties on.
daizu:url is the URL on which all the
other URLs in your site will be based (unless you
override it for parts of the site). It will usually be the address of
your site's homepage. dc:title should be a title for
the site as a whole. The default templates put that at the top of each
page, but you can customize that if you want. You can set up a
website directory something like this:
svn mkdir example.com svn ps daizu:url http://www.example.com/ example.com svn ps dc:title "Example website" example.com
(Note: if you plan to publish lots of websites with Daizu then you might want to group them into other directories, but it shouldn't cause problems to rename or move the website directories later.)
(Note: a ‘website’ doesn't necessarily mean a domain. You can set the URL to something with a path in if Daizu will only be publishing part of the content on a domain. It must however be an absolute URL including the domain.
Inside your website directory, at least if you want to start with the default templates, add the content from the Daizu source code package, which is in the content directory. If you use this default content and don't customize the templates then you'll end up with a site which looks like this one. To install the default content you might want to do something like this:
cd example.com svn mkdir style cp ~/daizu-source/content/style/* style/ svn add style/*
You'll probably also want to add an article, just so whether things
are working properly. To add a homepage (which will get the same
URL as you specified on the directory), create a
file in your website directory called _index.html and put
a bit of XHTML content in it. The content should
be block elements like p because Daizu will add the trimmings
like the html and body elements.
Your file will only get published as an article (with all the
templating to add the rest of the page) if you mark it as being an
article, which you do by setting the daizu:type property
to the value article. You might also want to add a title,
unless it should be the same as the one you put on the website directory,
which can be inherited. Something like this should do the trick:
svn add _index.html svn ps daizu:type article _index.html svn ps dc:title Homepage _index.html svn ci _index.html
Creating the database
The content from the repository will be loaded into a PostgreSQL database. Although the repository keeps all the current and historical content, the database provides faster access to it, and keeps track of things that Subversion doesn't know about, like the URLs associated with files.
I'm assuming you've set up PostgreSQL so that you can create a database and initialize it with tables. You can then create and load the database like this, using the db.sql file in the Daizu source package:
createdb web_content psql web_content <db.sql
Setting up authors
It's a good idea to tell Daizu who the author of content is. You can tweak the templates to display this information or not, as you like. By default blog articles display the name of the author if known, but other articles don't.
To start with, you'll probably want to pick a single username for the main author of your content, and associate that with the directory for your website in the Subversion content repository like this:
svn ps daizu:author geoff example.com
You need to provide information about this author in the database. Unfortunately there isn't a tool for doing this, so you'll have to write some SQL. Something like this should suffice:
insert into person (username) values ('geoff'); insert into person_info (person_id, path, name, email, uri) values (1, '', 'Geoff Richards', 'geoff@laxan.com', 'http://www.laxan.com/');
There has to be a value in both of those tables for any authors
you refer to in a daizu:author property.
See the documentation for author metadata for full details of how Daizu uses this information.
Configuration file
You need a configuration file to tell Daizu things like the URL of the Subversion repository, and the name of the PostgreSQL database, as well as more interesting things like which plugins to load. Daizu's configuration is stored in an XML file. The source package contains an example called config.xml.
See the documentation for the configuration file format for more details.
You can put your configuration file anywhere, and set an environment
variable DAIZU_CONFIG to point to its location. Alternatively,
Daizu will also find it if you put it at /etc/daizu/config.xml.
Configuring Apache
I'm assuming you'll be serving Daizu's output through Apache,
in which case you'll probably want to tell Apache to redirect the
browser if a URL has changed, to take advantage of
Daizu's URL tracking. This example would work with
the example configuration file
(you'll need to make sure that the two paths to the map files match the
redirect-map and gone-map attributes in your
configuration):
RewriteEngine On # Redirect old URLs to the new location of a resource. RewriteMap redirectmap txt:/var/www/example.com-redirect.map RewriteCond %{REQUEST_FILENAME} !-f RewriteCond ${redirectmap:$1} ^(.+)$ RewriteRule ^(/.*) %1 [R=permanent,L] # Indicate that an old URL's resource has been removed. RewriteMap gonemap txt:/var/www/example.com-gone.map RewriteCond %{REQUEST_FILENAME} !-f RewriteCond ${gonemap:$1} !^$ RewriteRule ^(/.*) - [gone,L]
The checks of REQUEST_FILENAME are so that things in the
maps won't take effect until the original files have been removed, so that
there's time for the new files to get in place before the old ones start
redirecting to them.
If you're expecting URLs to change all the time then
it might be safer to use temporary redirects (HTTP
status 302) by removing the =permanent above), and perhaps
take out the ‘gone’ mapping and just allow dead URLs to
return a 404 status (‘not found’). This is because the permanent redirects
(HTTP status 301) and ‘gone’ responses
(HTTP status 410) can both be potentially cached
forever by browsers or web caches.
Managing publication
The actual process of publishing things with Daizu isn't as smooth as it should be yet, mainly because Daizu doesn't know how to figure out what stuff should be published after you've committed your changes to the repository, so you have to tell it. It also doesn't know how to delete files for URLs which have been removed.
You'll be using the daizu program for all of this.
To start with, check out a working copy to use as the ‘live’ working copy. This is what you'll publish the live sites from. You might want to have other working copies tracking different branches (and in the future so that multiple users can work on content in them). For now though just create one:
daizu checkout
From now on I'll assume that daizu can find the
configuration file, and that it has access to the appropriate libraries,
but if you haven't installed and set up everything yet you can still
run it from inside the source package like this:
DAIZU_CONFIG=config.xml perl -Ilib bin/daizu checkout
Note that the checkout process (or at least loading revisions, which happens automatically first) can be incredibly slow and use vast amounts of memory if you have lots of content, or lots of changes to larges numbers of files. This will get fixed eventually.
You'll then need to update the url table in the database.
This will also publish the rewrite maps after you change things in ways
which lead to URLs changing or becoming inactive.
daizu update-all-urls
And then you can publish the files for a given website. The output
will appear in your configured document root. There isn't yet any way
to have it copied to a remote location, so you might have to run
rsync or something to get it to your web server.
daizu publish-all http://www.daizucms.org/