Xiong has asked for the wisdom of the Perl Monks concerning the following question:

What overall strategy do you employ when creating a directory structure for development, management, and delivery of a web application?

Over the years, I've employed several different strategies; I've become dissatisfied with each one. As my projects become more advanced and I attempt to formalize my development process, it seems that directory structure becomes more complex and opaque, when the ideal is to be straightforward and transparent.

Here are some of the most important goals I have in mind:

All the approaches that I've used have led to some nasty choppery-about. Perhaps when it comes time to upload to server, I have to go hunting for local files and do mulitple cd on server to put everything where it's supposed to go. Perhaps I find myself copying local files mulitple times, or dropping a lot of symlinks around. Often, I spend far too much time just digging around, trying to figure out where I put some file. I feel a more disciplined approach to directory structure would help.

Directory structure (for an individual developer, not part of a team) is a personal decision and I don't expect a one-size-fits-all answer. But I would like to see what others have found that works for them.

Replies are listed 'Best First'.
Re: Overall Directory Organization
by dsheroh (Monsignor) on Nov 10, 2009 at 11:53 UTC
    Here's what I'm currently using, although it's admittedly not CPAN-compatible, since I use git to deploy my webapps, so CPAN isn't a concern for them. Assuming I'm building My Web App:
    • ~/src/my_web_app/
      • TODO
      • MyWebApp/
        • (general project-specific modules defining the underlying object/data model)
        • CGI/
          • (plugin modules for connecting the object/data model to the web interface)
      • cgi/
        • index.fcgi
        • tpl/
          • (page-generation templates)
        • (other misc files which need to be accessible by web)
      • local/
        • (misc host-specific support files which, for whatever reason, aren't put into the main git repo)
      • t/
        • (test scripts)
      • util/
        • (any command-line tools specific to the project, including cron scripts)
    With this structure, installing on a new host is a simple matter of cloning the project out of git and symlinking the cgi/ directory into the host's web root. Depending on how the host's operating system handles paths doing a ../ from a symlinked directory, it may also be necessary to symlink MyWebApp/ into one of the dirs in @INC, but that's usually not required, thanks to FindBin. (Obviously, I only work with *nix-derived OSes. I don't know whether Windows has a suitable equivalent to symlinks or, if it does, what that might be.)

    If I were to want to build a CPAN distribution out of one of these projects, I would expect it to mostly just be a matter of creating a distribution dir (call it dist/ and symlinking the relevant bits into it - MyWebApp/ into dist/lib/, t/ into dist/ to replace the default dist/t/, and cgi/ and util/ to... well... I don't know where because I've never packaged executables for CPAN, only modules.

Re: Overall Directory Organization
by bibliophile (Prior) on Nov 10, 2009 at 15:24 UTC
    Here's what I use:
    • ~/prj/myproject/trunk
      • bin - cgi-bin stuff
      • conf - config files
      • devdocs - just like it sounds
      • externals - catch-all for support programs
      • logs
      • modules - module hierarchy
      • templates - mostly mimics modules hierarchy
      • updates - sequentially numbered SQL files to update database structure to "current version"
      • install.sh - single command to move everything necessary into "live" /opt/myproject, unlink/relink conf files, reload apache, etc
    All under version control (svn), and Trac.

    This layout (copped mainly from some CGI-App docs) works well enough for me, but then my current projects aren't particularly large; YMMV