blog.Resource

Archive:

News-Feeds:


RSS 2.0
RSS 0.91
RDF
ATOM 0.3
July 16, 2009

Making of the tutorial

Category: Robert Lemke

By: Robert Lemke

Documentation is really a phenomenon. It's surely the least attractive task for a developer. However, I often made the experience that once you got into the flow it can be quite fun and looking at the finished text may give you the same feeling like looking on a big stack of wood after an afternoon's chopping session.

Now it's that time again, I'm in writing mode. We definitely need a good tutorial for FLOW3 which give potential users a nice ride through the cool features of the framework. But that's not the only reason why we're writing one. For me the tutorial also serves as a specification: Many times I'd explain steps to setup or use FLOW3 the way I would like them to be, not necessarily matching reality. Then, after writing the chapter, I brood over a possible implementation together with Karsten or one of our off site team member.

One result of yesterday's "Documentation-Driven-Development" session is some renaming of important directories, a luxury we still allow ourselves while FLOW3 is in alpha stage. We found that the directory "Public" doesn't describe well enough that it is the web root of your application - and nothing else. Therefore we renamed it to "Web". The "Global" packages directory contains all packages of the standard distribution which essentially are the framework of your application while the "Local" packages directory is reserved for packages specific to your application. Consequently we renamed those to "Framework" and "Application" respectively. These changes won't have any bad side effects on your existing FLOW3 projects, the most you'll have to do, if at all, is renaming these directories in your local copy.

I also literally fought against file permissions. We have a kind of tricky scenario with FLOW3: while applications will usually be web based and therefore being run by the webserver's user, we also provide a powerful command line interface which is used by other users. We have lots of directories and files which require write access in different ways - cache files need to be written, resources being published to the web directory and an SQLite database being accessed. We use touch() at some places in FLOW3 which annoyingly requires the user being owner of the file to be touched.

All in all there was too much which could go wrong due to deficient file permissions – and we didn't like the approach of most other frameworks which recommend a chmod 777 on most directories. Finally I wrote the following instructions and modified our setfilepermissions.sh script. If you've got the time, please try it out and report any potential glitches - I hope you won't find any ;-)

"We recommend setting ownership of directories and files to the webserver's group. All users who also need to launch FLOW3 are also added this group. Setting the correct permissions is easily done with a little script delivered with the FLOW3 distribution:

setfilepermissions.sh commandlineuser webuser webgroup

In practice you'll use the script like this:

myhost:~ johndoe$ cd /opt/local/apache2/htdocs/myapp
myhost:myapp johndoe$ ./Packages/Framework/FLOW3/Scripts/setfilepermissions.sh johndoe _www _www

Now that the file permissions are set, all users who plan using FLOW3 from the command line need to join the webserver's group. On a Linux machine this can be done by typing:

myhost:~ johndoe$ sudo usermod -a -G _www johndoe

On a Mac you can add a user to the web group with the following command:

myhost:~ johndoe$ sudo dscl . -append /Groups/_www GroupMembership johndoe

You will have to exit your shell / terminal window and open it again for the new group membership to take affect."


comments

comment #1
Gravatar: martin martin July 16, 2009 11:02
im really excited to see the tutorial :)
great work ;)

comment #2
Gravatar: Francois Francois July 16, 2009 11:37
Yep, writing documentation can be a chore, but it's also a vital part of any project. As you point out it also helps to iron out things or sometimes find bugs because you actually have to test all the features you mention.

And yes, there's a very good feeling at the end of the exercise.

comment #3
Gravatar: Mario Rimann Mario Rimann July 16, 2009 13:08
Looking forward to see the documentation! Thanks for also keeping an eye on these things beside pure coding work!

Sorry, comments are closed for this post.