Experimenting with DokuWiki

Wikis are just one more thing I've always wanted to play around with. And my job has, once again, afforded me the opportunity to do just that. We're currently using an engine called DokuWiki, so I decided to kick its tires and see what it — and wikis in general — are all about.

DokuWiki's front page describes it thusly:

"DokuWiki is a standards compliant, simple to use Wiki, mainly aimed at creating documentation of any kind. It is targeted at developer teams, workgroups and small companies. It has a simple but powerful syntax which makes sure the datafiles remain readable outside the Wiki and eases the creation of structured texts. All data is stored in plain text files – no database is required."

No Database

That last little bit — the lack of a database — is actually one of the things that makes DokuWiki unique. It is both its strength and its potential weakness, and one of its defining characteristics.

If you are looking to install a documentation engine for a small to medium-sized workgroup, it's true: DokuWiki is great. It's very easy to install and only requires Apache and PHP be running on your server. This means it can be installed on any Mac OS X machine without having to install or configure much beyond Personal Web Sharing. I say, "much" because you will have to activate (not install) PHP, which isn't too hard for savvy users, but isn't exactly mom-friendly either. Still, it beats having to also install and enable a database application like MySQL, which most other wikis require. So DokuWiki is relatively easy to setup.

That lack of a database is nice, in that it makes installation quick and easy. But it's also a potential drawback, albeit a minor one. DokuWiki writes all its entries to flat files and that could affect scalability, and to some extent performance, if your wiki ever became extremely large. The merits of databases vs. flat files for storing data are debated all over the Internets, but databases usually only offer a significant advantage when dealing with complex, relational data, and that advantage is usually only seen by the developer. For small to mid-sized or even large-ish sites, DokuWiki is great. If you’re worried your wiki might need to grow very large some day (like, to the point where load balancing across multiple servers is required, for instance — we're talking big!), DokuWiki may not be for you. Otherwise, the flat file system offers additional advantages, like easy-to-parse and repair backups, to name just one.

Wherefore Wiki?

That said, once installed, DokuWiki is very easy to use. It does use its own markup for page layout, but that markup is exceedingly sensible and easy to learn. My biggest stumbling block was getting started: How do you create a page? Well, once you know, it's pretty simple, but figuring it out took me a minute. The easiest way to create a page, is to navigate to that page. If the page doesn't exist, DokuWiki allows you to create it. See? Easy! Maybe too easy!

So what's it for? Well, I'll tell you, TASB was almost a wiki rather than a blog. While both are types of Content Management Systems (CMSes), and essentially do the same thing — allow a person to easily and rapidly build and read a structured store of text and media data — the difference is intent.

Blogs — and therefore blog engines — are geared toward personal, diaristic, periodic writing. They're usually organized chronologically, like a diary, and require no special markup when creating entries. Entries, once made, are rarely revised. One of the things I enjoy about writing this blog is that it's a bit more personal. It's a record of personal experience as much as, if not more than, documentation. So I stuck with using the blog format. I like to be chatty.

Wikis, on the other hand, are made to be accessed like a reference, like an encyclopedia, for instance. They're not chronological, but are usually ordered and read alphabetically; and wiki articles are made to be maintained and updated as information changes. Wikipedia is a great example of this. There is also a blog called the Tao of Mac that uses a wiki engine for content management, showing that, in the end, the two types of engines do essentially the same thing. They simply present different capabilities to their users based largely on the purpose of the site.

Conclusion

If you're looking for a quick, easy-to-use and easy-to-maintain storehouse of information (either for yourself, or for use with others), a wiki is a great thing to have. Need to document a procedure for your workgroup? Put it on the wiki. Need to let everyone know where that essential file is? Put it on the wiki. Just want to jot down some notes for the general use? Put 'em on the wiki.

After using one for a few days I can already see just how damn handy a wiki is to have. And DokuWiki is super-easy both to install and learn. If you just need something small to document procedures or productions — or if you're just looking to dip your toe into the world of wikis — DokuWiki is very nice indeed.

UPDATE:

I've edited the article for clarity and accuracy regarding the use of flat file systems vs. relational databases. Thanks to DokuWiki's author for pointing out the error.

Portable Home Directories Part 3: Keychain Oddities

Hey, here's a weird one: I finally got my home account back to working order after my experiment with PHDs only to find that iCal couldn't open any of my online calendars. It kept saying the password was missing from Keychain, then refusing to let me add one, saying that the "Keychain could not be found."

The Keychain application also refused to read my keychains. The keychains were there, as they always had been, in ~/Library/Keychains. Keychain.app just refused to see them. Refused to add them — or anything else for that matter — as well. Keychain First Aid reported everything as fine, but the damn things just wouldn't show up.

Suspecting some sort of weird, post-PHD permissions snafu, I copied the Keychain application to my Desktop and then launched it. This seemed to remedy the problem; the keychains became visible in Keychain.app. But upon re-launching iCal, my keychains became inaccessible again.

Mucking around in Keychain.app, everything looked fine. But I wanted to make sure that my "login" keychain was set to be the default. So I selected another keychain I have, right-clicked it and chose "Make keychain 'systemsboy' Default," then did the same to the login keychain, thus resetting it as the default keychain.

After doing this I launched iCal and the password complaints were gone; the calendars all loaded properly. Launching Keychain again, however, seemed to break everything. Again! WTF? No matter what I did, Keychain would eventually lose track of my keychains, and this would cause any application that relied on them to screw up. But I did eventually figure it out.

The solution? Well, it's so simple and so idiotic it's hardly worth a post. But here you go: I rebooted.

That's right. A simple reboot and all my troubles were gone.

Remember, kids: reboot, reboot, reboot!

Portable Home Directories Part 2: Oh God, Make it Stop

Last week I began testing the Apple Portable Home Directories feature. I'd heard a lot of good buzz, but my experience was pretty terrible. Of course I was doing things my own way, and not the Apple way, which is always a bit dicey.

Almost Proper

Wanting to get PHDs working, I decided to try doing things a bit more by the book. I set up our NFS Home Account Server as an NFS Reshare and shared it out over AFP. I also set my home accounts up properly in WGM, using the AFP share as my network home, and a local folder as my local one.

But PHD kept incorrectly syncing things, to the point where I've actually now lost some data. Seems PHD, when it syncs, is for some reason using the data on the network drive as the master data set. Files I've modified before leaving for work have been reverted back to their old versions — the ones on the network — over night. (Which is weird considering the fact that I was logged out.)

I'm sure this works in a perfectly standard environment, with no existing users and no NFS Reshares, when set up from scratch. But I have to say, I could not be more frustrated with PHDs. So I'm giving up for now and setting my home account back to the local drive. Of course, even reverting back to a non-managed, non-PHD, local account is difficult in this case.

Cache Insanity

The reason for this — and one of the things that's made testing PHDs so difficult in general — is the insane level of caching the server does with regards to PHDs. Caching is so aggressive that, even after disabling PHDs on the server and restarting the client machine, the SyncAgent on the client continues to attempt to sync my homes. If I try to stop it I get an error that says I can't stop it because I don't have a PHD. I'm a big fan of irony, but not in my server software, thank you very much.

So now the PHD service is incorrectly syncing my local home account with a network home it shouldn't even see. Thousands of conflicts are occurring. I'm losing data. Though I've disabled the service, the settings persist. This is terrible. Horrible. Godawful.

And there is no sanctioned, GUI way to stop this from happening.

Freedom!

Eventually I was able to stop the errant syncing by running the ever-trusty:

sudo dscacheutil -flushcache

Jesus! What a kludge!

You can imagine how difficult this has made my testing. I can't be sure that any change I've made on the server is actually happening on the client, so it's impossible to know where this is failing or what I might be doing wrong without starting from scratch every time I make a configuration change. And starting from scratch is pretty damned difficult as well, as the PHD settings are persistent to a fault.

Is That All There Is?

I'm not sure what to do with PHDs at this point. I don't think they're useful for our environment, or for any existing users. Testing them is downright painful. And data loss is a real possibility, and not a risk I'm willing to take with other users' data.

So, after a couple weeks of some very frustrating testing, I'm afraid I'll have to pass on PHDs. It's a nice idea, but not ready for prime time from where I sit.

There's a slight chance I'll try PHDs from scratch with a fresh home account, just to see if it works at all. But we'll see. I'm pretty annoyed at this point.

More annoyed than I ever was with Windows Roaming Profiles. And that's a feat.

Portable Home Directories Part 1: What a Mess!

Now that I've tried it myself, I've very much enjoyed the advantages that having a network home account has offered. I've also rather disliked some of the disadvantages. Ultimately, the biggest drawback has been that when our production crew is doing a lot of rendering, my home account slows to a crawl and I can't get work done. Okay, I can, but not without a lot of swearing, and the fellas in the other cubicles just ain't digging that, believe me.

After some water-cooler-side conversation, and some excellent comments by my excellent readers, I've decided I might be just be a perfect candidate for something that may offer the best of both worlds.

Portable Home Directories (PHDs), as they're called by Apple, essentially allow a user to keep and work from a local copy of his network home account. The local account is synced up with the network account using various strategies, which I'll talk about in a bit. It's essentially an intelligent implementation of Windows' crappy Roaming Profiles. The big difference is those strategies I mentioned.

Windows' Roaming Profiles are problematic, particularly in production environments where users store a lot of data, because Windows simply hard syncs those profiles at login and logout. This means that if you've generated a lot of data in any given session, you're in for a long wait when you log out — and another long wait if you log into another machine — while Windows syncs your local and network profiles. It's a nice idea — giving you the centrality of a network account and the responsiveness of a local one — but it fails in practice because it is, essentially, dumb, causing the sync process to ruin the experience.

The experience we're going for here is, of course, seamlessness. Or as close to it as possible. So: I want to be able to log in to my workstation and have the responsiveness and normalcy of a local account, but I then want to be able to log in to another workstation and have my documents follow me throughout a given facility. Moreover, I want the synchronization of said documents to be as invisible as possible to the user. It should "just work." With as little waiting and confusion as possible.

This is, of course, easier said than done.

Apple takes a noble stab at this with its Portable Home Directory settings. See, where Microsoft simply syncs account data at login and logout, Apple affords some granularity in what gets synced and at what times. Apple gives you precise control over what gets synced, as well as allowing for not just login and logout syncing, but periodic syncing as well. Smart! And it could make all the difference.

But I'm getting ahead of myself again. Let's actually step through the process of creating a Portable Home Account. I'll show where it shines and where it falls apart for me.

Activate Mobility Preferences

• This all starts in Workgroup Manager. So fire that up and navigate to the user you want on Portable Homes.
• Make sure that user's current home account is a Network Home Account (i.e., it lives on a server somewhere).
• Click the "Preferences" button from the toolbar, and then open the "Mobility" pane. This is where all the action happens.

  

Set Account Creation Options

• The first thing to set up is how and when the local portable account is created. Click on the Account Creation tab and set Manage: to Always.
• Since I already have a network home account that I've been using from an NFS share (on a non-Apple server), I set my user to "Create mobile account when user logs in" using the "default sync settings." I assumed this would copy everything over from the network account to the local drive and start the ball rolling fresh, but that's not what happened. More on that in a bit.

  

• Under Account Creation's Options tab I set a custom path that pointed to a folder that contained a local version of my home account that I'd rsynced previously. Again, I did this thinking it would speed the initial sync process, but that turned out to not be the case.

  

Set Sync Rules

• Finally it's time to define how the syncing between local and network homes will behave. This is the real genius behind the Portable Home Directory system, and what distinguishes it from Roaming Profiles.
• First under the Rules tab you have "Login & Logout Sync." This allows you to set specific items to sync only at login and logout. The suggested defaults for this are mainly your account settings, i.e. your entire ~/Library folder. This is quite sane, and I stuck with this setting.

  

• Note the "Merge with user's settings" checkbox. I initially checked this, but later found it problematic. It was useful on my first sync, but it doesn't appear to track deletions and such, so I ended up disabling it.
• Also of note is the "Skip items" section. This allows for what rsync users would call exclusions. This also greatly speeds syncing as you can exclude unneeded items such as cache and trash. I stuck with the sane defaults here as well.
• Next up are your Background Sync settings. Again, very sane defaults are provided: We back up your entire home account, periodically, in the background. Skip the usual suspects and don't merge.

  

• Finally, under Options, we can set the frequency with which the server will run the background sync.

  

• I also set the option to "Show status in menu bar." This, as you'll see, becomes quite useful for the way I ultimately ended up using this feature.

Some Disclaimers

Portable Home Directories are actually not specifically intended for the sort of use-case we're applying them to here. PHDs are actually designed for users with laptops that come and go onto a network that is also populated with stationary workstations. It's really made to be used in conjunction with network home accounts, allowing laptop users to use network home accounts without being completely tethered to the network.

So to be clear, this is an experiment. I'm doing things a bit outside the norm. (I mean, what fun would it be if I weren't.) And any problems I had were likely because of this fact. Still, it's hinted at in the documentation that PHDs can be used for users of non-portable machines to some advantage, so I wanted to see how we could apply them to our (okay, my) particular situation.

I started off a bit outside the realm of the typical first time setup. I had two things at the outset that essentially represented a test of how we might migrate to a PHD-style system: I had a network home account already populated with data, and I had a copy of that data on a local hard drive. This represents our typical user. But I was also hoping that I'd be able to use these to get the Portable Homes process underway more speedily. This was not the case at all.

Initial Experiences

The first thing that happened when I logged into my newly Portable Homes-activated account was that I was greeted with a prompt asking me if I wanted to create a portable home.

I chose to do so ("Yes"), since that was pretty much what I was here to do. And upon login I was greeted, not with my previously set up network home account nor my rsynced local account, but rather with the standard boilerplate skel account you see when creating a new user. Worse, the server seemed to get confused as to where my home account should be placed on the local drive. Though I had defined it on my server as a custom path, it seemed to want to go in a folder called "User" on the specified drive, no matter what I entered for the custom path. Apparently, for me anyway, the custom path — and my hopes of speeding the sync process — just plain old didn't work.

After this I decided to try again. I moved my custom folder off the local drive and, in Mobility Preferences, simply defined the drive I wanted to use for my Portable Home. I also chose to "Merge with user's settings" for this go 'round under the Rules section of the Mobility prefs. The thought was that this should pull down my network home account and create a local version from it. And this is exactly what happened. And for a time life was good and I thought I was done. I thought I'd found my magic settings. But the next day I logged in to find that once again my account had reverted back to the default, first-login settings. Yikes!

(Here I'd just like to point out the benefits of having a backup of your entire home account if you're going to play around with this. Or just use a spare, dummy account. I actually did lose data numerous times during my testing, as you'll see in Part 2.)

After poking around a bit I discovered that my machine had logged me into my network home. Or at least that's where the Finder went when I hit Command-Shift-H. But my home account settings were the defaults, not my network home account settings. WTF? Logging out and logging back in I found myself in what I considered to be the right local location, and all my custom settings had returned. But this was clearly getting weird and flaky. And no matter how I configured things, the weirdness persisted. The biggest problem, though, was the fact that my local and network home accounts never synced in the background. And that was sort of the most important part.

Manual Sync

For a time I used Portable Home Directories the only way I could get it to work for me. Remember that tickbox to "Show status in menu bar?" Well, it turns out that you can use this menubar widget to manually sync your local and network home accounts. And manual syncing actually worked okay for me. In fact, it was the only way I could get my network and local data in sync.

During this time I pretty much using the default Mobility settings, but my account was on my Work drive. Portable Homes had placed it at:

/Volumes/Work/systemsboy.xahomes

for some strange reason, but I could live with that. Every so often — particularly if I thought I might be going to another machine and logging in as myself — I'd hit "Sync Home Now" in the Menubar pulldown.

This would begin the Home Sync process. The process is far from immediate, but it's not too slow. It takes a few minutes. Once it's done I can verify that my network and local homes are synced up.

Conflicts that the service couldn't resolve were handled similarly to iPhone-to-AddressBook conflicts, though, with the usual PHD flakiness: often conflicts occurred where they shouldn't have.

But the biggest problem with Manual Sync was that logging in to another computer failed. A popup alert appeared telling me I was unable to log in at this time because "an error occurred." Great.

I was really hoping for this to be seamless, of course. But it just may not be possible with this particular setup. The best I can get out of Portable Homes so far is not much better than a glorified rsync script with a pretty GUI for running it and some semblance of conflict resolution. And it completely breaks my ability to log into other computers.

Conclusion (For Now)

In the end I decided that my troubles were likely due to the fact that I was not working in the typical Mac OS X idiom. It's my guess that Portable Homes failed for me in this instance mainly because my network home account is on a completely different, non-Apple server, one that my Mac Server is not set up to share as a network home location. I would venture that if you set Portable Homes up just like it says in the manual, using Apple kit and AFP and the like (possibly AFP reshares would work), Portable Homes works like a charm. But if you don't you'll get some strangeness like I did. Ah, the joys of the bleeding edge!

On my first shot at Portable Homes I experienced a number of surprises and inconsistencies. While Portable Homes is a great idea, and in theory looks to be perfect for someone like me, there are major pitfalls in a complex, multi-platform environment that prevent it from being usable for much of anything. But Portable Homes has potential and I plan to delve more into how to get it working for us in our complex environment. In our next installment I'll be trying a setup more closely aligned with the Apple-sanctioned method for implementing PHDs. We'll see how it goes.

Software Update Server

I can't believe I never wrote this up, but I've been using the Software Update Server included with Mac OS X Leopard Server since I upgraded the servers at my old job. If your network — or Apple's servers — are ever slow to get updates, having your own centralized SU Server can make a world of difference. But it's most useful when you have a bunch of Macs you need to update all at once. Try doing ten or so over the Internet at the same time. You'll get errors and failures, and you'll kill your network pretty quickly as all those updates come in at once. But updating a lab full of Macs from your own dedicated Software Update Server will not only not fail, it'll actually be quite fast since your using only internal bandwidth, of which you should have plenty. Setting one of these up is pretty easy, but there are a couple gotchas I always have to remember. So here we go.

1. Activate the service in Server Admin.

   

2. Configure the service. I like to configure the SU Server to "Automatically copy all new updates from Apple." This is the easiest, and I like things easy. But otherwise I use the default settings.

   

3. Start the service and list the updates. And here's one of the gotchas: when you first start the service there is no indication that anything is happening. There is no progress bar and nothing will appear in the list of updates. But in fact the SU Server is downloading all the updates (several Gigs) in the background. The easiest way to prove that this is actually happening is to run the df command, then run it again. You should see your root drive getting gradually fuller as the server downloads the updates. This first download will take a long time. I like to let it go overnight.

   

4. When you return the next morning, the list should be populated with all the available updates, as seen above. (Also, you see about 10-15 GBs of data in the Software Update Server's data store, which is here: /usr/share/swupd/html/content/downloads/.) The last step then — and the thing I often forget — is to tell your client Macs where to get their Software Updates. To do this you'll need a computer list in Workgroup Manager. Add any computers you want to use your SU Server to the list. Then go to the Preferences pane for the group and select Software Update. Set the URL for the SU Server to: http://server.domain.com:8088/index.sucatalog

   

5. After saving that configuration, logging out and logging back in should be all you need to do on your clients to pick up the server. After doing so, run Software Update and you'll see the name of your SU Server in the menubar of the interface. This confirms you're successfully getting updates from the server.

   

Congrats! You're not a total moron. Enjoy!

UPDATE:

Reader Dennis points out in the comments that individual clients can be configured to look to the SUServer for updates without being part of a WGM group or managed by the server at all. This is done by modifying a preference on the client system, which you would do thusly:

sudo defaults write /Library/Preferences/com.apple.SoftwareUpdate CatalogURL "http://systemsboy.su.server.com:8088/"

That command can, of course, be sent en masses using Apple Remote Desktop's "Send Unix Command" directive.

And, if you want to revert to the standard method of checking for updates, looking at Apple's servers, delete the "CatalogURL" entry in the preference file by running:

sudo defaults delete /Library/Preferences/com.apple.SoftwareUpdate CatalogURL

Thanks for the tip, Dennis!